Zendesk Guide の記事を一括でバックアップしてみた

こんばんは、筧（カケイ）です。

Zendesk Guide の記事棚卸しに伴い、記事のバックアップを一括で取得したい・・・！

このような場面に最近遭遇したのですが、こちらの方法が紹介されていたのでやってみました。

Backing up your knowledge base with the Zendesk API | Zendesk

前提条件

• Python 3 をインストール済みの環境がある
• Zendesk Guide の記事を取得できるユーザー権限を持っている

やってみた

以下の流れで作業します。

1. フォルダ作成
2. ファイル作成
3. ファイル編集
4. ファイルの実行
5. 実行結果確認

1.フォルダ作成

ローカルに、backups という名前のフォルダを作成します。

mkdir backups

2.ファイル作成

作成したフォルダ配下に、make_backup.py という名前のファイルを作成します。

touch make_backup.py

こんな構成になります。

backups
└── make_backup.py

3.ファイル編集

作成したファイルを編集します。以下のスクリプトを貼り付けてください。

make_backup.py

import os
import datetime
import requests
import csv

credentials = '{your_zendesk_email}', '{your_zendesk_password}'
zendesk = '{https://your_instance.zendesk.com}'
language = '{some_locale}'

date = datetime.date.today()
backup_path = os.path.join(str(date), language)
if not os.path.exists(backup_path):
    os.makedirs(backup_path)

log = []

endpoint = zendesk + '/api/v2/help_center/{locale}/articles.json'.format(locale=language.lower())

while endpoint:
    response = requests.get(endpoint, auth=credentials)
    if response.status_code != 200:
        print('Failed to retrieve articles with error {}'.format(response.status_code))
        exit()
    data = response.json()

    for article in data['articles']:
        if article['body'] is None:
            continue
        title = '<h1>' + article['title'] + '</h1>'
        filename = '{id}.html'.format(id=article['id'])
        with open(os.path.join(backup_path, filename), mode='w', encoding='utf-8') as f:
            f.write(title + '\n' + article['body'])
        print('{id} copied!'.format(id=article['id']))

        log.append((filename, article['title'], article['author_id']))

    endpoint = data['next_page']

with open(os.path.join(backup_path, '_log.csv'), mode='wt', encoding='utf-8') as f:
    writer = csv.writer(f)
    writer.writerow( ('File', 'Title', 'Author ID') )
    for article in log:
        writer.writerow(article)

ハイライトの4箇所について編集します。

1箇所目

make_backup.py

credentials = '{your_zendesk_email}', '{your_zendesk_password}'

適切なクレデンシャル情報にします。以下は基本認証を使用する場合です。

• {your_zendesk_email}：Zendesk ログイン時のメールアドレス（例：kakei@example.com）
• {your_zendesk_password}：Zendesk ログイン時のパスワード

API トークンを使用する場合は注意が必要です。メールアドレスの末尾に、/token を忘れずにつけましょう。

• '{your_zendesk_email}'：Zendesk メールアドレス（例：kakei@example.com/token）
• '{your_zendesk_password}'：Zendesk API トークン

基本認証と API トークンについて詳しく知りたい方は以下を参照ください。

How can I authenticate API requests? | Zendesk

2箇所目

make_backup.py

zendesk = '{https://your_instance.zendesk.com}'

ご自身のサブドメインを確認して、適切な URL にします。

• {https://your_instance.zendesk.com}：ご自身のサブドメインに変更した URL（例：https://obscura.zendesk.com）

ご自身のサブドメインの確認方法は以下を参照ください。

Where can I find my Zendesk subdomain? | Zendesk

3箇所目

make_backup.py

language = '{some_locale}'

取得する記事の言語によって、適切な指定をします。

• {some_locale}：ja ※日本語の記事を指定する場合
• {some_locale}：en-US ※英語の記事を指定する場合

言語コードの詳細については以下を参照ください。

Language codes for Zendesk-supported languages | Zendesk

4箇所目

make_backup.py

endpoint = zendesk + '/api/v2/help_center/{locale}/articles.json'.format(locale=language.lower())

取得する記事の言語によって、適切な指定をします。

• {locale}：ja ※日本語の記事を指定する場合
• {locale}：en-US ※英語の記事を指定する場合

Zendesk Guide はカテゴリ・セクション単位で記事を管理しますが、こちらのカテゴリ・セクション単位でバックアップを取得したい場合は、以下のようにエンドポイントを指定することで取得可能です。 {locale} には取得する記事の言語を、{category_id}、{section_id} には各 ID を設定してください。

カテゴリ単位

endpoint = zendesk + '/api/v2/help_center/{locale}/categories/{category_id}/articles.json'.format(locale = language.lower())

• {category_id}：Guide 管理の対象カテゴリの編集画面で URL に表示される ID

セクション単位

endpoint = zendesk + '/api/v2/help_center/{locale}/sections/{section_id}/articles.json'.format(locale = language.lower())

• {section_id}：Guide 管理の対象セクションの編集画面で URL に表示される ID

カテゴリ・セクションの詳細については以下を参照ください。

Organizing knowledge base content in categories and sections | Zendesk

各エンドポイントの詳細については以下を参照ください。

List Articles | Zendesk

4.ファイルの実行

ファイルの編集・保存ができたら、ファイル実行します。

python make_backup.py

5.実行結果確認

backups 配下に以下の構成でバックアップが保存されます。 各記事ごとに html ファイルが作成されます。

backups
├── 2020-09-30
│   └── ja
│       ├── xxxxxxxxxxxx.html
│       ├── yyyyyyyyyyyy.html
│       ├── zzzzzzzzzzzz.html
│       └── _log.csv
└── make_backup.py

_log.csv には、File,Title,Author ID のカラムで整理された記事の一覧を確認できます。

_log.csv

File,Title,Author ID
xxxxxxxxxxxx.html,test1,123456789101
yyyyyyyyyyyy.html,test2,123456789101
zzzzzzzzzzzz.html,test3,123456789101

クレデンシャル情報をハードコーディングしているので、念の為ファイル実行したらすぐにクレデンシャル情報を削除しておきましょう。

終わりに

Zendesk Guide の記事の一括バックアップ方法のご紹介でした。

スクリプトの細かい説明は割愛しましたが、詳細を知りたい方は冒頭に貼った紹介元の記事を確認してください。

以上、 筧（カケイ） がお送りしました。それでは皆さん良い夜を！