カスタム検索インデックスの構築、バックアップの作成、または記事を別のプラットフォームに同期するなど、Zendeskヘルプセンターのコンテンツにプログラムでアクセスしたい場合、Zendesk Guide APIが最適なツールです。しかし、多くのREST APIと同様に、始めるのは大変に感じるかもしれません。認証の設定、ページネーションの処理、および選択できるさまざまなエンドポイントがあります。
このガイドでは、APIを使用してZendesk Guideから記事をリスト表示および取得するために知っておく必要のあるすべてのことを説明します。認証、最初のリクエストの作成、大規模なコンテンツライブラリのページネーションの処理、およびニーズに合わせて調整できる実際のコード例について説明します。
開始するために必要なもの
API呼び出しに入る前に、次の前提条件が整っていることを確認してください。
- 管理者またはエージェントアクセス権を持つZendeskアカウント：APIトークンを生成し、ヘルプセンターのコンテンツにアクセスするには、適切な権限が必要です。
- APIトークン：Zendesk管理センターから生成されます（ステップ1で説明します）。
- REST APIの基本的な知識：HTTPメソッド（GET、POST）、JSON形式、およびリクエストヘッダーの理解。
- APIリクエストを行うためのツール：これは、cURL、Postman、またはPythonやNode.jsなどのプログラミング環境である可能性があります。
- プランのレート制限の認識：Zendeskは、サブスクリプションティアに基づいて異なるリクエスト制限を適用します。
レート制限といえば、プランに応じて使用できる制限は次のとおりです。
| プラン | 1分あたりのリクエスト数 (RPM) |
|---|---|
| Essential | 10 RPM |
| Team | 200 RPM |
| Professional | 400 RPM |
| Enterprise | 700 RPM |
| High Volume Add-on | 2,500 RPM |
これらの制限を超えると、429エラーが発生します。APIは、Support APIのリクエスト/分制限に従い、あるAPIのリクエストは、別のAPIのレート制限に対してカウントされません。
Zendesk Guide APIの構造を理解する
ZendeskヘルプセンターAPIは、ナレッジベースのコンテンツとプログラムでやり取りできるREST APIです。リクエストを行う前に、コンテンツがどのように編成されているかを理解しておくと役立ちます。
Zendesk Guideは、階層構造に従います。
- カテゴリ (Category)：コンテンツを整理するための最上位のコンテナです。
- セクション (Section)：カテゴリ内に存在し、関連する記事をグループ化します。
- 記事 (Article)：実際のコンテンツ（ヘルプトピック、FAQ、ガイド）です。
APIを介して記事をリスト表示する場合、ヘルプセンター全体のすべての記事を取得するか、特定のカテゴリまたはセクションでフィルタリングできます。APIは、タイトル、本文コンテンツ、作成者情報、下書きステータスなどの記事メタデータを含むJSONレスポンスを返します。
認証には、メールアドレスとAPIトークンを使用したベーシック認証を使用します。形式は{email_address}/token:{api_token}で、Authorizationヘッダー用にBase64でエンコードされます。
重要な注意点の1つは、レスポンスは常に、リクエストを行うユーザーの権限に従ってフィルタリングされることです。したがって、エージェントまたは管理者ではなくエンドユーザーとして認証している場合、そのユーザーが表示する権限を持つ記事のみが表示されます。
ステップ1：API認証を設定する
APIの使用を開始するには、APIトークンが必要です。トークンを生成する方法は次のとおりです。
- 管理者としてZendeskアカウントにサインインします。
- 管理センター (Admin Center) → チャネル (Channels) → APIに移動します。
- **設定 (Settings)**タブをクリックします。
- まだ有効になっていない場合は、**トークンアクセス (Token Access)**を有効にします。
- **+**ボタンをクリックして、新しいトークンを追加します。
- トークンにわかりやすい名前を付けます（「記事エクスポートスクリプト」など）。
- トークンをすぐにコピーします。Zendeskは1回しか表示しません。
トークンを取得したら、簡単なcURLリクエストで認証をテストできます。
curl https://{your_subdomain}.zendesk.com/api/v2/help_center/articles \
-v -u {your_email}/token:{your_api_token}
{your_subdomain}をZendeskサブドメインに、{your_email}をアカウントのメールアドレスに、{your_api_token}を生成したばかりのトークンに置き換えます。
認証に成功すると、200ステータスコードと記事を含むJSONレスポンスが表示されます。401エラーが発生した場合は、トークンがアクティブであり、メール/トークンの組み合わせが正しいことを再確認してください。
一般的な認証の問題：
- 401 Unauthorized：トークンが非アクティブであるか、メール/トークンの形式が間違っています。
- 403 Forbidden：ユーザーにリソースにアクセスする権限がありません。
- 404 Not Found：エンドポイントURLが正しくありません。
ステップ2：基本的なAPI呼び出しですべての記事をリスト表示する
認証されたので、記事を取得しましょう。記事をリスト表示するための主要なエンドポイントは次のとおりです。
GET /api/v2/help_center/articles
requestsライブラリを使用した完全なPythonの例を次に示します。
import requests
from requests.auth import HTTPBasicAuth
subdomain = 'your_subdomain'
email = 'your_email@example.com'
api_token = 'your_api_token'
url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles'
response = requests.get(
url,
auth=HTTPBasicAuth(f'{email}/token', api_token),
headers={'Content-Type': 'application/json'}
)
data = response.json()
articles = data['articles']
for article in articles:
if not article['draft']: # Skip drafts
print(f"{article['id']}: {article['title']}")
レスポンスには、articles配列が含まれており、各記事オブジェクトには次のフィールドが含まれています。
| フィールド (Field) | 説明 (Description) |
|---|---|
id | 一意の記事識別子 (Unique article identifier) |
title | 記事のタイトル (Article title) |
body | 記事のHTMLコンテンツ (HTML content of the article) |
section_id | この記事を含むセクションのID (ID of the section containing this article) |
draft | 記事が下書きかどうかを示すブール値 (Boolean indicating if the article is a draft) |
created_at | 作成時のISO 8601タイムスタンプ (ISO 8601 timestamp of creation) |
updated_at | 最終更新時のISO 8601タイムスタンプ (ISO 8601 timestamp of last update) |
author_id | 記事を作成したユーザーのID (ID of the user who created the article) |
デフォルトでは、このエンドポイントは1ページあたり30件の記事を返します。記事がさらに多い場合は、ページネーションを処理する必要があります（ステップ3で説明します）。
ステップ3：大規模な記事リストのページネーションを処理する
ページネーションは、多くの開発者が行き詰まる場所です。Zendesk Guide APIは、カーソルページネーション（推奨）とオフセットページネーションの2つのページネーション方法をサポートしています。
カーソルページネーション (Cursor pagination) は最新のアプローチであり、APIレスポンスの「next」リンクをたどることで機能します。大規模なデータセットの場合、より効率的であり、オフセットページネーションのページ制限はありません。
カーソルページネーションを使用するには、リクエストに?page[size]=100を追加します（100が最大です）。すべてのページですべての記事を取得する完全なPythonの実装を次に示します。
import requests
from requests.auth import HTTPBasicAuth
def get_all_articles(subdomain, email, api_token):
articles = []
url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'
while url:
response = requests.get(
url,
auth=HTTPBasicAuth(f'{email}/token', api_token),
headers={'Content-Type': 'application/json'}
)
if response.status_code != 200:
print(f"Error: {response.status_code}")
break
data = response.json()
articles.extend(data['articles'])
# Get the next page URL from the links object
url = data.get('links', {}).get('next')
print(f"Retrieved {len(articles)} articles so far...")
return articles
all_articles = get_all_articles('your_subdomain', 'your_email', 'your_token')
print(f"Total articles: {len(all_articles)}")
重要なのは、data['links']['next']を確認することです。最後のページに到達すると、この値はnullになり、ループが終了します。
オフセットページネーション (Offset pagination) は古い方法であり、最大100ページに制限されています。per_pageおよびpageパラメーターを使用します。Zendeskは、新しい実装にはカーソルページネーションを推奨しています。
大規模なデータセットをページネーションする場合は、レート制限に注意してください。記事が数千件ある場合は、リクエスト間に短い遅延を追加することを検討してください。
import time
time.sleep(0.5) # 500ms delay
ステップ4：記事をフィルタリングおよびソートする
APIには、記事リストをフィルタリングおよびソートするためのいくつかの方法が用意されています。
ラベルによるフィルタリング (Filtering by labels)： 記事ラベル（ProfessionalおよびEnterpriseプランで利用可能）を使用している場合は、それらでフィルタリングできます。
GET /api/v2/help_center/articles?label_names=photos,camera
これにより、指定されたすべてのラベルを持つ記事のみが返されます。ラベルのマッチングでは大文字と小文字が区別されます。
ソート (Sorting)：
sort_byおよびsort_orderパラメーターを使用して、順序を制御します。
| ソートオプション (Sort option) | 説明 (Description) |
|---|---|
position | [コンテンツの配置]ページの手動順序（デフォルト）(Manual order from the Arrange Content page (default)) |
title | タイトルによるアルファベット順 (Alphabetical by title) |
created_at | 作成時間 (Creation time) |
updated_at | 最終更新時間 (Last update time) |
edited_at | タイトルまたは本文が最後に編集された時間 (Last time title or body was edited) |
例：/api/v2/help_center/articles?sort_by=updated_at&sort_order=desc
増分エクスポート (Incremental exports)：
記事を外部システムに同期するには、start_timeパラメーターを使用して増分エンドポイントを使用します。
GET /api/v2/help_center/incremental/articles?start_time=1704067200
start_timeはUnixエポックタイムスタンプです。これにより、その時間以降に作成または更新された記事のみが返されます。
カテゴリまたはセクションによるリスト表示 (Listing by category or section)： 特定のカテゴリから記事を取得するには：
GET /api/v2/help_center/categories/{category_id}/articles
または、特定のセクションから：
GET /api/v2/help_center/sections/{section_id}/articles
関連データのサイドローディング (Sideloading related data)： API呼び出しを減らすために、関連リソースをサイドロードできます。
GET /api/v2/help_center/articles?include=users,sections,categories
これにより、完全なユーザー、セクション、およびカテゴリオブジェクトがレスポンスに含まれるため、その情報のために個別のAPI呼び出しを行う必要はありません。
一般的なユースケースとコード例
一般的なシナリオの実用的な実装を次に示します。
検索インデックス作成のためにすべての記事をエクスポートする (Export all articles for search indexing)： このスクリプトは、公開されているすべての記事をJSONファイルにエクスポートし、下書きを除外し、必要なフィールドのみを含めます。
import json
import requests
from requests.auth import HTTPBasicAuth
def export_articles_for_search(subdomain, email, api_token, output_file):
articles = []
url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'
while url:
response = requests.get(url, auth=HTTPBasicAuth(f'{email}/token', api_token))
data = response.json()
for article in data['articles']:
if not article['draft']:
articles.append({
'id': article['id'],
'title': article['title'],
'body': article['body'],
'url': article['html_url'],
'updated_at': article['updated_at']
})
url = data.get('links', {}).get('next')
with open(output_file, 'w') as f:
json.dump(articles, f, indent=2)
print(f"Exported {len(articles)} articles to {output_file}")
エラー処理のベストプラクティス (Error handling best practices)： API呼び出しで発生する可能性のあるエラーは常に処理してください。
response = requests.get(url, auth=auth)
if response.status_code == 429:
# レート制限に達しました。待機して再試行してください (Rate limit hit wait and retry)
time.sleep(60)
response = requests.get(url, auth=auth)
elif response.status_code == 401:
print("認証に失敗しました。APIトークンを確認してください (Authentication failed check your API token)")
sys.exit(1)
elif response.status_code != 200:
print(f"APIエラー：{response.status_code} (API error: {response.status_code})")
print(response.text)
eesel AIを使用したZendesk Guideコンテンツの管理
Zendesk Guide APIを使用すると、ヘルプセンターのコンテンツにプログラムでアクセスできますが、そのコンテンツを効果的に管理および活用できるのがeesel AIです。
記事を同期するためのカスタムスクリプトを構築する代わりに、当社のAIエージェントはZendesk Guideに直接接続し、ヘルプセンターのコンテンツから自動的に学習します。これは次のことを意味します。
- ノーコード設定 (No-code setup)：Zendeskアカウントを接続すると、eesel AIが記事を自動的にインポートします。
- 常に最新 (Always up to date)：Zendeskで記事を更新すると、eesel AIが変更を学習します。
- 多言語サポート (Multi-language support)：Zendeskがサポートする80以上の言語のいずれかの記事で動作します。
- スマートな応答 (Smart responses)：当社のAIは、ヘルプセンターのコンテンツを信頼できる情報源として使用して、顧客の質問に答えます。
エンジニアリングのオーバーヘッドなしでAIを活用したサポートを構築しようとしているチームにとって、eesel AIは、適切な記事コンテンツを適切なタイミングで同期、インデックス作成、および取得するという複雑さを処理します。AI Copilotから始めて、エージェントの応答を下書きし、自信がついたら、完全なAIエージェント自動化にレベルアップできます。
今すぐZendesk Guide APIで構築を開始しましょう
Zendesk Guide APIの操作を開始するために必要なものがすべて揃いました。簡単なまとめを次に示します。
- Zendesk管理センターからAPIトークンを生成します。
- メールとトークンを使用してベーシック認証で認証されたリクエストを作成します。
- 大規模な記事ライブラリの場合は、カーソルページネーションを使用してページネーションを処理します。
- クエリパラメーターを使用してフィルタリングおよびソートし、必要なデータを正確に取得します。
記事の作成または更新、翻訳の管理、または記事の添付ファイルの操作などの高度な機能については、公式のZendesk APIドキュメントを確認してください。
また、AI応答の強化、カスタム検索の構築、自動化されたワークフローの作成など、ヘルプセンターのコンテンツでさらに多くのことを行いたい場合は、eesel AIがカスタム統合コードを作成せずに、より迅速に目標を達成するのにどのように役立つかを検討してください。
よくある質問
この記事を共有
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
