API에서 데이터를 다운로드하여 CSV에 저장해야 하는 경우가 많습니다. 아마도 일부 데이터를 분석하고 싶을 것입니다. 또는 데이터를 다른 데이터 세트와 결합하려고 합니다.

이 문서에서는 Help Scout의 API를 사용하는 동안 이 작업을 수행하는 방법을 살펴보겠습니다. Help Scout은 팀에서 고객과 통신할 때 사용하는 헬프 데스크 솔루션입니다.

Help Scout 사서함 중 하나에서 "대화"를 검색하고 해당 데이터를 CSV에 저장합니다. 이러한 대화에는 이메일을 보낸 사람, 제목, 날짜, 대화가 할당된 팀원 및 종료 시간이 포함됩니다.

앱 ID 및 비밀번호 얻기

Help Scout API에서 데이터를 가져오기 전에 앱 ID와 비밀을 생성해야 합니다. 먼저 HelpScout에 로그인하고 "내 프로필"로 이동합니다.



왼쪽 메뉴에서 "내 앱"을 클릭합니다.



"내 앱 만들기"버튼을 클릭하고 이름을 입력합니다. 이 앱으로 인증하는 사용자가 없으므로 리디렉션을 위해 아무 URL이나 입력할 수 있습니다. 나는 보통 회사 사이트의 URL을 넣습니다.



"만들기"버튼을 클릭합니다. 생성되면 앱의 ID와 Secret이 표시됩니다.



Help Scout에 있는 동안 대화를 검색하려는 사서함을 엽니다. URL에서 나중에 필요한 사서함의 ID를 찾을 수 있습니다.

액세스 토큰 받기

사용자를 인증하지 않기 때문에 인증을 위해 Help Scoutclient credentials flow를 사용합니다. 그러기 위해서는 먼저 액세스 토큰을 가져와야 합니다.

먼저 필요한 패키지를 가져와야 합니다. 나는 API로 작업할 때 거의 항상 the "requests" package을 사용합니다. 또한 생성된 시간과 종료된 시간이 있으므로 여기에서 해결 시간을 계산하고 싶습니다. 이를 위해 Python's "datetime" library 을 사용하겠습니다.

import csv
import datetime
import requests

다음으로 앱의 ID와 암호를 토큰 끝점으로 보내야 합니다. 요청을 하고 그들이 반환하는 JSON에서 access_token 키를 가져와 이를 수행할 수 있습니다.

# The token endpoint.
auth_endpoint = 'https://api.helpscout.net/v2/oauth2/token'

# Preparing our POST data.
post_data = ({
    'grant_type': 'client_credentials',
    'client_id': YOUR_HELPSCOUT_APP_ID,
    'client_secret': YOUR_HELPSCOUT_APP_SECRET
})

# Send the data.
r = requests.post(auth_endpoint, data=post_data)

# Save our token.
token = r.json()['access_token']

모든 대화를 다운로드할 때까지 루프를 계속 진행할 방법이 필요합니다. Help Scout API에는 확인할 수 있는 totalPages 키가 포함되어 있습니다.

이를 처리할 수 있는 몇 가지 다른 방법이 있지만 저는 설명이 필요 없는 플래그를 false로 설정하는 것을 좋아합니다.

all_conversations = False
page = 1

그런 다음 인증 헤더를 준비해야 합니다.

# Prepare our headers for all endpoints using token.
endpoint_headers = {
    'Authorization': 'Bearer {}'.format(token)
}

CSV 파일 준비

이제 토큰이 있으므로 CSV 파일을 설정할 수 있습니다. 이전에 Python에서 CSV로 작업한 적이 없다면 check out my "Reading From and Writing to CSV Files in Python" article .

먼저 CSV 파일을 열고 헤더를 작성합니다.

# Creates our file or rewrites it if one is present.
with open('conversations.csv', mode="w", newline='', encoding='utf-8') as fh:
    # Define our columns.
    columns = ['ID', 'Customer Name', 'Customer email addresses', 'Assignee', 'Status', 'Subject', 'Created At',
               'Closed At', 'Closed By', 'Resolution Time (seconds)']  
    csv_writer = csv.DictWriter(fh, fieldnames=columns) # Create our writer object.
    csv_writer.writeheader() # Write our header row.

대화를 다운로드하여 CSV에 넣기

이제 액세스 토큰과 CSV가 열렸으므로 대화를 검색할 차례입니다. Help Scout의 API는 페이지가 매겨진 형식으로 대화를 보냅니다.

CSV에 쓸 수 있도록 with open() 문 안에 이 모든 들여쓰기를 유지해야 합니다.

while 루프 내에서 대화의 첫 번째 페이지를 얻습니다.

while not all_conversations:
    # Prepare conversations endpoint with the status of conversations we want and the mailbox.
    conversations_endpoint = 'https://api.helpscout.net/v2/conversations?status=all&mailbox=YOUR_MAILBOX_ID&page={}'.format(
        page
    )
    r = requests.get(conversations_endpoint, headers=endpoint_headers)
    conversations = r.json()

다음으로 이 페이지 내의 각 대화를 순환하여 CSV에 저장합니다. JSON에는 대화에 따라 누락될 수 있는 키가 많기 때문에 저장할 수 있을 만큼만 데이터를 정리하고 처리해야 합니다.

# Cycle over conversations in response.
for conversation in conversations['_embedded']['conversations']:

    # If the email is missing, we won't keep this conversation.
    # Depending on what you will be using this data for,
    # You might omit this.
    if 'email' not in conversation['primaryCustomer']:
        print('Missing email for {}'.format(customer_name))
        continue

    # Prepare customer name.
    customer_name = '{} {}'.format(
        conversation['primaryCustomer']['first'],
        conversation['primaryCustomer']['last']
    )

    # Prepare assignee, subject, and closed date if they exist.
    assignee = '{} {}'.format(conversation['assignee']['first'], conversation['assignee']['last']) \
        if 'assignee' in conversation else ''
    subject = conversation['subject'] if 'subject' in conversation else 'No subject'
    closed_at = conversation['closedAt'] if 'closedAt' in conversation else ''

    # If the conversation has been closed, let's get the resolution time and who closed it.
    closed_by = ''
    resolution_time = 0
    if 'closedByUser' in conversation and conversation['closedByUser']['id'] != 0:
        closed_by = '{} {}'.format(
            conversation['closedByUser']['first'], conversation['closedByUser']['last']
        )
        createdDateTime = datetime.datetime.strptime(conversation['createdAt'], "%Y-%m-%dT%H:%M:%S%z")
        closedDateTime = datetime.datetime.strptime(conversation['closedAt'], "%Y-%m-%dT%H:%M:%S%z")
        resolution_time = (closedDateTime - createdDateTime).total_seconds()

그런 다음 결과를 CSV에 씁니다.

# Write row to CSV
csv_writer.writerow({
    'ID': conversation['id'],
    'Customer Name': customer_name,
    'Customer email addresses': conversation['primaryCustomer']['email'],
    'Assignee': assignee,
    'Status': conversation['status'],
    'Subject': subject,
    'Created At': conversation['createdAt'],
    'Closed At': closed_at,
    'Closed By': closed_by,
    'Resolution Time (seconds)': resolution_time
})

마지막으로, 모든 대화를 검색했는지 확인하기 위해 우리가 있는 페이지에 대해 'totalPages' 키를 확인합니다. 그렇지 않은 경우 현재 페이지를 증가시킨 다음 프로세스를 다시 시작합니다.

if page == conversations['page']['totalPages']:
    all_conversations = True
    continue
else:
    page += 1

엄청난! 이제 스크립트를 실행할 준비가 되었습니다. 이 코드를 모두 함께 볼 수 있습니다in my GitHub gist here.

다음 단계

계속해서 스크립트를 실행하여 Help Scout 사서함에서 모든 대화를 검색하십시오.

백업만 받으려고 했다면 이제 가도 좋습니다. 데이터에서 데이터 분석을 수행하려는 경우 이제 Excel에서 파일을 열거나 Pandas를 사용할 수 있습니다. 또는 이것이 데이터 파이프라인의 첫 번째 단계인 경우 이제 파이프라인의 다음 단계에서 작업을 시작할 수 있습니다.