Zendesk GuideナレッジベースAPI：2026年版完全開発者ガイド

Zendeskとの統合を構築している場合、またはナレッジベースのコンテンツをプログラムで管理したい場合、ZendeskヘルプセンターAPI（Zendesk GuideナレッジベースAPIとも呼ばれます）がそのための入り口となります。記事を外部検索システムに同期したり、バックアップソリューションを構築したり、コンテンツをAIナレッジベースにフィードしたりするなど、このREST APIはそれを実現するためのツールを提供します。

その仕組みと効果的な使用方法について詳しく見ていきましょう。

Zendesk GuideナレッジベースAPIとは？

ZendeskヘルプセンターAPIは、Zendesk Guideナレッジベースのコンテンツをプログラムで管理できるREST APIです。Zendeskのより広範なAPIエコシステムの一部であり、リクエストとレスポンスの両方にJSONを使用します。

このAPIでできることは次のとおりです。

• コンテンツの読み取り：記事、セクション、カテゴリをフェッチして外部で使用します。
• コンテンツの書き込み：記事をプログラムで作成、更新、アーカイブします。
• 翻訳の管理：多言語コンテンツを大規模に処理します。
• 検索とフィルタリング：ラベル、日付、その他の条件を使用して特定のコンテンツを見つけます。

APIは標準的なRESTの規則に従います。ベースURLはhttps://{your-subdomain}.zendesk.com/api/v2/help_center/のようになり、すべてのレスポンスはリクエストを行うユーザーの権限に従ってフィルタリングされます。つまり、匿名ユーザーは公開コンテンツのみを表示でき、エージェントは権限に応じて内部記事にアクセスできます。

認証の開始

API呼び出しを行う前に、認証を行う必要があります。Zendeskは、APIトークンとOAuth 2.0の2つの主要な方法を提供しています。

APIトークン認証（サーバーサイドスクリプトに推奨）

APIトークンは、開始する最も簡単な方法です。Zendesk管理センターのアプリと統合 > API > Zendesk APIで生成します。

属性	詳細
トークン制限	アカウントあたり256（大規模アカウントの場合は最大2,048）
形式	{email_address}/token:{api_token}
ヘッダー	Authorization: Basic {base64_encoded_credentials}

実際の使用例は次のとおりです。

curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

cURLの-uフラグは、Base64エンコードを自動的に処理します。コードでヘッダーを手動で構築する場合は、メールアドレスとトークンをコロンで結合し、結果をBase64エンコードして、Authorizationヘッダーに追加します。

OAuth 2.0（ユーザー向けアプリケーション向け）

クライアントサイドアプリケーションを構築している場合、または個々のユーザーの代わりに行動する必要がある場合は、OAuthがより適切な選択肢です。これはBearerトークンを使用します。

curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

ここでの主な利点は、OAuthがCORSをサポートしているため、ブラウザベースのアプリケーションに適していることです。APIトークンはCORSをサポートしておらず、サーバーサイドでの使用に限定されます。

**セキュリティに関する注意：**すべての接続はTLS 1.2以上を使用する必要があります。トークンを安全に保管し、バージョン管理にコミットしないでください。

コアAPIエンドポイントと操作

ヘルプセンターAPIは、カテゴリ、セクション、記事の3つの主要なコンテンツタイプを中心に構成されています。カテゴリにはセクションが含まれ、セクションには記事が含まれるという階層構造として考えてください。

記事の操作

記事のエンドポイントは、最も多くの時間を費やす場所です。主な操作は次のとおりです。

すべての記事をリストする：

GET /api/v2/help_center/articles.json

これは、記事のページネーションされたリストを返します。クエリパラメータを使用して結果をフィルタリングできます。

パラメータ	目的	例
label_names	ラベルでフィルタリング	?label_names=faq,billing
sort_by	ソートフィールド	?sort_by=updated_at
sort_order	ソート方向	?sort_order=desc
start_time	増分エクスポート	?start_time=1704067200

特定の記事を取得する：

GET /api/v2/help_center/articles/{article_id}.json

記事を作成する：

POST /api/v2/help_center/sections/{section_id}/articles.json

必須フィールドには、title（タイトル）、locale（ロケール）、permission_group_id（権限グループID）が含まれます。body（HTMLコンテンツ）、author_id（作成者ID）、label_names（ラベル名）、draft（下書き）ステータスなどのオプションフィールドも設定できます。

記事を更新する：

PUT /api/v2/help_center/articles/{article_id}.json

記事をアーカイブする：

DELETE /api/v2/help_center/articles/{article_id}.json

コンテンツ階層エンドポイント

エンドポイント	目的
GET /api/v2/help_center/categories.json	すべてのカテゴリをリストする
GET /api/v2/help_center/categories/{id}/sections.json	カテゴリ内のセクションをリストする
GET /api/v2/help_center/sections.json	すべてのセクションをリストする
GET /api/v2/help_center/sections/{id}/articles.json	セクション内の記事をリストする

関連データのサイドローディング

便利な機能の1つはサイドローディングで、1つのリクエストに関連データを含めることができます。記事のリクエストに?include=users,sections,categoriesを追加すると、レスポンスにはIDだけでなく、作成者、セクション、カテゴリの完全なオブジェクトが含まれます。

ページネーションの効率的な処理

ページネーションは、多くの開発者が最初に引っかかる場所です。ヘルプセンターAPIは2つのページネーション方法をサポートしており、適切な方法を選択することが重要です。

カーソルベースのページネーション（推奨）

カーソルページネーションは最新のアプローチであり、大規模なデータセットで大幅に優れたパフォーマンスを発揮します。これを使用するには、リクエストにpage[size]を追加します。

GET /api/v2/help_center/articles.json?page[size]=100

レスポンスには、has_moreブール値を持つmetaオブジェクトと、nextおよびprev URLを持つlinksオブジェクトが含まれます。

{
  "articles": [...],
  "meta": {
    "has_more": true
  },
  "links": {
    "next": "https://.../articles.json?page[size]=100&page[after]=xxx",
    "prev": null
  }
}

has_moreがfalseになるまで、next URLに従ってください。以下はPythonの例です。

import requests
from base64 import b64encode

def fetch_all_articles(subdomain, email, token):
    base_url = f"https://{subdomain}.zendesk.com/api/v2/help_center/articles.json"
    credentials = b64encode(f"{email}/token:{token}".encode()).decode()
    headers = {"Authorization": f"Basic {credentials}"}

    articles = []
    url = f"{base_url}?page[size]=100"

    while url:
        response = requests.get(url, headers=headers)
        data = response.json()
        articles.extend(data["articles"])

        url = data["links"]["next"] if data["meta"]["has_more"] else None

    return articles

オフセットベースのページネーション（レガシー）

オフセットページネーションはまだ機能しますが、制限があります。2023年8月現在、この方法を使用して10,000件を超えるレコード（100ページ）を取得することはできません。試行すると、400 Bad Requestエラーが発生します。

GET /api/v2/help_center/articles.json?per_page=100&page=2

レスポンスには、next_pageおよびprevious_page URLが含まれます。next_pageがnullになったら停止します。

**結論：**新しい統合にはカーソルページネーションを使用してください。より高速で信頼性が高く、ハード制限はありません。

一般的な統合パターン

基本を理解したので、開発者が通常本番環境でこのAPIをどのように使用するかを見てみましょう。

外部検索インデックス作成

一般的なユースケースは、ElasticsearchやAlgoliaなどの外部検索エンジンでZendeskの記事をインデックスすることです。パターンは次のようになります。

1. カーソルページネーションを使用してすべての記事をフェッチします。
2. HTML本文をプレーンテキストに変換します（タグを削除します）。
3. 記事ID、タイトル、本文テキスト、URLをインデックスします。
4. 増分更新のためにstart_timeパラメータを使用して定期的な同期を設定します。

重要なのは、検索結果がZendeskにリンクバックできるように、インデックスに元の記事URLを保持することです。

コンテンツのバックアップと移行

バックアップワークフローでは、ナレッジベース全体をエクスポートする必要がある場合があります。

1. すべてのカテゴリを反復処理します。
2. 各カテゴリについて、そのセクションを取得します。
3. 各セクションについて、その記事を取得します。
4. 完全な記事オブジェクト（HTML本文を含む）をバックアップストレージに保存します。

これにより、コンテンツ階層が保持され、復元が簡単になります。

AIおよびRAGシステム統合

増え続けるユースケースは、AI搭載のサポートのためにZendeskコンテンツをRetrieval-Augmented Generation（RAG）システムにフィードすることです。ワークフローには通常、次のものが含まれます。

1. APIを介して記事を抽出します。
2. HTMLをMarkdownまたはプレーンテキストに変換します。
3. ベクターストレージ用にコンテンツをチャンク化します。
4. 引用のために元のURLを保持します。

ここで、eesel AIのようなツールが役立ちます。カスタムETLパイプラインを構築する代わりに、Zendeskアカウントを直接接続して、ナレッジベースのコンテンツを使用して質問に回答するAIエージェントを用意し、元の記事への引用を完了することができます。

レート制限とベストプラクティス

レート制限を理解することで、統合が大規模に壁にぶつかるのを防ぎます。

プランごとのリクエスト制限

プラン	サポート/ヘルプセンターAPI制限
Suite Team	200リクエスト/分
Suite Growth	400リクエスト/分
Suite Professional	400リクエスト/分
Suite Enterprise	700リクエスト/分
Suite Enterprise Plus	2,500リクエスト/分

出典：Zendeskレート制限ドキュメント

レート制限エラーの処理

制限を超えると、APIは429ステータスコードを返し、Retry-Afterヘッダーに待機する秒数を示します。コードは次のことを行う必要があります。

1. 429レスポンスを確認します。
2. Retry-Afterの値を取得します。
3. その秒数だけ待機してから再試行します。
4. 繰り返しの失敗に対して指数バックオフを実装することを検討してください。

以下は、Pythonの簡単な再試行デコレータです。

import time
import requests
from functools import wraps

def with_rate_limit_retry(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        max_retries = 3
        for attempt in range(max_retries):
            response = func(*args, **kwargs)
            if response.status_code != 429:
                return response

            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)

        raise Exception("Rate limit exceeded after retries")
    return wrapper

@with_rate_limit_retry
def api_call(url, headers):
    return requests.get(url, headers=headers)

パフォーマンスのヒント

• カーソルページネーションを使用する：より高速で、10,000件のレコード制限はありません。
• サイドローディングを有効にする：複数の呼び出しを行う代わりに、1つのリクエストで関連データをフェッチします。
• 積極的にキャッシュする：記事のコンテンツはそれほど頻繁には変更されません。
• 増分エクスポートを使用する：start_timeパラメータを使用すると、変更されたコンテンツのみをフェッチできます。

検討すべき代替アプローチ

カスタムAPI統合の構築が常に正しい選択であるとは限りません。以下は、決定するための簡単なフレームワークです。

次の場合にAPIを直接使用します。

• データ変換を完全に制御する必要がある場合
• 専任のエンジニアリングリソースがある場合
• ユースケースがユニークまたは複雑な場合

次の場合にZendeskのネイティブ機能を使用します。

• 検索で外部コンテンツを表示するだけの場合：フェデレーション検索を使用します。
• 基本的なコンテンツ管理が必要な場合：組み込みのUIを使用します。

次の場合に統合プラットフォームを使用します。

• RAGパイプラインを構築せずにAI搭載の回答が必要な場合
• エンジニアリングリソースなしで迅速なセットアップが必要な場合
• メンテナンスのオーバーヘッドなしで継続的な同期が必要な場合

これは、eesel AIが適合する場所です。Zendeskコンテンツを抽出、変換、同期するためのカスタムスクリプトを作成する代わりに、数分でアカウントを接続し、ナレッジベースを使用して顧客の質問に回答するAIチームメイトを取得できます。API統合、コンテンツインデックス作成、回答生成を処理し、より価値の高い作業に集中できるようにします。

Zendeskで強力なナレッジ統合を構築する

ZendeskヘルプセンターAPIは、高度なナレッジ管理ワークフローを作成するための構成要素を提供します。カスタム検索インデックスの構築、システム間のコンテンツの移行、または記事をAIプラットフォームへのフィードなど、認証、ページネーション、およびレート制限を理解することで、成功に向けて準備できます。

小さく始めてください。記事のリストをフェッチし、ページネーションを試して、より複雑な統合を構築します。そして、ビジネス上の問題を解決するよりもデータパイプラインの維持に多くの時間を費やしていることに気付いた場合は、統合プラットフォームの方が適しているかどうかを検討してください。

Zendeskの設定をAI機能で強化したい場合は、eesel AIがナレッジベースをインテリジェントなサポートエージェントに変える直接的な統合を提供します。カスタムAPI開発は必要ありません。