Zendesk Guide APIコンテンツ管理：完全な開発者ガイド

ヘルプセンターのコンテンツを大規模に管理する場合、手動で行うと面倒になります。別のプラットフォームから記事を移行する場合でも、マーケティングチームからアセットを同期する場合でも、複数のブランドにわたってコンテンツを整理する場合でも、Zendesk Guide APIを使用すると、ナレッジベースをプログラムで制御できます。

このガイドでは、Zendesk Guide API (ZendeskガイドAPI) コンテンツ管理について知っておく必要のあるすべてのことを説明します。認証、コアエンドポイント、実践的な実装パターン、およびAPIを使用する意味と、eesel AIのような代替手段について説明します。

必要なもの

始める前に、以下を確認してください。

• Guideが有効になっているZendeskアカウント（Suite Teamプラン以上）
• APIトークンを生成するための管理者アクセス
• REST APIとJSONの基本的な知識
• 優先するHTTPクライアント（cURL、Postman、またはPythonのようなプログラミング言語）

Zendesk Guide API認証について

Zendesk Guide API (ZendeskガイドAPI) は、他のZendesk APIと同じ認証パターンを使用します。知っておく必要のあることは次のとおりです。

APIトークン認証（推奨）

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

重要な詳細：

• 資格情報を{email_address}/token:{api_token}としてフォーマットします。
• Authorizationヘッダーの文字列全体をBase64エンコードします。
• 最大256個のアクティブなトークンを持つことができます（レガシーアカウントの場合は2048個）。
• トークンは管理者を含む任意のユーザーを偽装できるため、安全に保管してください。

cURLリクエストの例：

curl https://{subdomain}.zendesk.com/api/v2/guide/medias \
  -v -u {email_address}/token:{api_token}

複数顧客アプリのOAuth

複数のZendesk (ゼンデスク) 顧客に配布される統合を構築している場合は、APIトークンではなくOAuthを使用する必要があります。通常のAPIトークンは、異なるZendeskインスタンス間で認証する必要があるアプリでは機能しません。

レート制限とSSL

ほとんどのエンドポイントでは、1分あたり700リクエストが許可されています。制限に達すると、429ステータスコードが表示されます。すべてのリクエストは、TLS 1.2以降のHTTPSを使用する必要があります。

コアコンテンツ管理エンドポイント

Guide API (ガイドAPI) は、さまざまなタイプのコンテンツを管理するためのいくつかのエンドポイントを提供します。最も役立つものを分解してみましょう。

Guide Medias API

Guide Medias APIは、Zendeskヘルプセンターのファイルアップロードとメディア管理を処理します。これは、画像または添付ファイルをプログラムで記事に追加する場合に不可欠です。

3段階のアップロードプロセス：

1. アップロードURLをリクエスト　コンテンツタイプとファイルサイズを指定して/api/v2/guide/medias/upload_urlにPOSTします。
2. ファイルをアップロード　ステップ1で返された署名付きURLにファイルをPUTします。
3. メディアオブジェクトを作成　アセットアップロードIDを指定して/api/v2/guide/mediasにPOSTします。

ファイルは最大20MBまで可能です。APIはULIDベースの識別子を使用します。これは、従来のUUIDとは異なり、ソート可能です。

Pythonの例：

import requests
import base64

auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {auth}", "Content-Type": "application/json"}

upload_data = {"content_type": "image/png", "file_size": 12345}
response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias/upload_url",
    json=upload_data,
    headers=headers
)
upload_url = response.json()["upload_url"]["url"]
asset_id = response.json()["upload_url"]["asset_upload_id"]

media_data = {"asset_upload_id": asset_id, "filename": "screenshot.png"}
media = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias",
    json=media_data,
    headers=headers
)

Content Tags API

コンテンツタグは、記事や投稿を整理するのに役立ちます。Content Tags APIを使用すると、タグをプログラムで作成、更新、および管理できます。

主な機能：

• POST/PUT/DELETEリクエストでタグを作成および管理します。
• /api/v2/guide/content_tags/jobsを介したバッチ操作（タグの削除またはマージ）。
• 名前プレフィックスでタグをフィルタリングします。
• IDまたは名前で昇順または降順にソートします。

バッチ操作は、重複するタグのマージや、ナレッジベース全体の古いタグの削除など、クリーンアップタスクに役立ちます。

Dynamic Content API

複数の言語をサポートしている場合は、Dynamic Content APIが不可欠です。{{dc.password_reset_instructions}}のようなプレースホルダーを使用して、ローカライズされたコンテンツバリアントを管理します。

仕組み：

• 各動的コンテンツアイテムには、デフォルトのロケールと複数のバリアントがあります。
• バリアントには、実際の翻訳されたテキストが含まれています。
• Zendesk (ゼンデスク) は、ユーザーのロケールに基づいて適切なバリアントを自動的に提供します。
• 一致するバリアントが存在しない場合は、デフォルトにフォールバックします。

**注：**動的コンテンツには、Professionalプラン以上が必要です。

External Content Sources API

External Content Sources APIを使用すると、フェデレーション検索が可能になり、外部システムからヘルプセンター検索に結果を取り込むことができます。

ユースケース：

• 学習管理システムからのコンテンツのインデックス作成
• 検索結果にフォーラム投稿を含める
• ヘルプセンターからJira (ジラ) の問題を検索可能にする

これには、ヘルプセンターマネージャーの権限が必要であり、Zendesk (ゼンデスク) のクローラーと連携して外部コンテンツをインデックス化します。

実践的な実装：メディアアップロードの自動化

実際のシナリオを見てみましょう。マーケティングチームはFigma (フィグマ) でスクリーンショットを作成し、Google Drive (グーグルドライブ) に保存します。これらをZendesk (ゼンデスク) メディアギャラリーに自動的に追加して、ライターが記事で使用できるようにします。

完全なPython実装を次に示します。

import requests
import base64
import time

class ZendeskMediaUploader:
    def __init__(self, subdomain, email, token):
        self.subdomain = subdomain
        self.base_url = f"https://{subdomain}.zendesk.com/api/v2"
        self.auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
        self.headers = {
            "Authorization": f"Basic {self.auth}",
            "Content-Type": "application/json"
        }

    def upload_file(self, file_path, content_type):
        """Upload a file to Zendesk media gallery."""
        file_size = os.path.getsize(file_path)
        filename = os.path.basename(file_path)

        # Step 1: Get upload URL
        upload_data = {"content_type": content_type, "file_size": file_size}
        resp = requests.post(
            f"{self.base_url}/guide/medias/upload_url",
            json=upload_data,
            headers=self.headers
        )
        resp.raise_for_status()

        upload_info = resp.json()["upload_url"]

        # Step 2: Upload file to signed URL
        with open(file_path, "rb") as f:
            put_headers = {
                "Content-Disposition": upload_info["headers"]["Content-Disposition"],
                "Content-Type": content_type,
                "X-Amz-Server-Side-Encryption": "AES256"
            }
            put_resp = requests.put(upload_info["url"], data=f, headers=put_headers)
            put_resp.raise_for_status()

        # Step 3: Create media object
        media_data = {
            "asset_upload_id": upload_info["asset_upload_id"],
            "filename": filename
        }
        media_resp = requests.post(
            f"{self.base_url}/guide/medias",
            json=media_data,
            headers=self.headers
        )
        media_resp.raise_for_status()

        return media_resp.json()["media"]

エラー処理のヒント：

• **401 Unauthorized：**トークンとメール形式を確認してください（/tokenを含める必要があります）。
• **403 Forbidden：**Guideマネージャーの権限があることを確認してください。
• **409 Conflict：**リクエストを再試行してください（一時的なエラー）。
• **429 Rate Limited：**指数バックオフを実装します。

Zendesk Guide API (ZendeskガイドAPI) と代替手段の使い分け

APIが常に正しい選択であるとは限りません。判断方法を次に示します。

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

• 別のプラットフォームから大量のコンテンツを移行する必要がある場合
• 既存のツールとのカスタム統合を構築している場合
• 反復的なタスク（一括タグ付けなど）を自動化する場合
• 継続的なメンテナンスのために利用できる開発リソースがある場合

次の場合に、ネイティブのZendesk (ゼンデスク) 機能の使用を検討してください。

• 時々手動でアップロードするだけでよい場合
• チームがZendesk (ゼンデスク) インターフェイスでの作業に慣れている場合
• フェデレーション検索がコードなしで外部コンテンツのニーズを満たしている場合

次の場合に、統合プラットフォームの使用を検討してください。

• カスタムコードなしで簡単な自動化が必要な場合
• ユースケースが標準のトリガーとアクションに適合する場合
• 開発時間なしで何かを迅速に実行したい場合

次の場合に、eesel AI (イーセルAI) の使用を検討してください。

カスタム統合を構築せずにZendesk (ゼンデスク) ナレッジベースをよりスマートにすることが目標の場合は、eesel AIを検討してください。コンテンツを同期するスクリプトを作成する代わりに、eeselはZendesk、Confluence、Google Docsなどのソースに直接接続します。

違いは次のとおりです。Guide API (ガイドAPI) を使用すると、コンテンツをプログラムでZendesk (ゼンデスク) に移動できます。eesel AI (イーセルAI) は、コンテンツが存在する場所でコンテンツをインデックス化し、Zendesk (ゼンデスク) 内で動作するAIエージェントを介してサポートチームがアクセスできるようにします。何も移行しません。コードを記述しません。ソースを接続すると、AIがそれらから学習します。

専任の開発者がいないチームにとって、これは統合された知識へのより速い道になる可能性があります。当社の価格は、Teamプランで月額299ドルから始まり、最大3つのボットと1,000回のAIインタラクションが含まれています。

ベストプラクティスとトラブルシューティング

セキュリティ

• APIトークンを環境変数に保存し、コードには絶対に保存しないでください。
• トークンを定期的にローテーションします（Zendesk (ゼンデスク) では最大256個まで持つことができるため、古いトークンを削除する前に新しいトークンを作成できます）。
• 異なる統合に個別のトークンを使用すると、他の統合に影響を与えることなく1つを取り消すことができます。

ページネーション

リストエンドポイントは、ページネーションされた結果を返します。大規模なデータセットには、カーソルベースのページネーションを使用します（データの変更には、オフセットページネーションよりも信頼性が高くなります）。

params = {"page[size]": 100}
while True:
    resp = requests.get(url, params=params, headers=headers)
    data = resp.json()

    # Process records
    for record in data["records"]:
        process(record)

    # Check for more pages
    if not data["meta"]["has_more"]:
        break
    params["page[after]"] = data["meta"]["after_cursor"]

テスト

• 本番環境で実行する前に、サンドボックス環境でテストします。
• Zendesk (ゼンデスク) のPostmanコレクションを使用して、エンドポイントを調べます。
• 開発中にAPI応答をログに記録して、エラー状態を理解します。

よくある落とし穴

• メールアドレスの/tokenサフィックスを忘れる
• 資格情報をBase64エンコードしない
• 大量操作中にレート制限に達する
• 再試行ロジックで409の競合を処理しない

Zendesk (ゼンデスク) コンテンツの管理をより効率的に開始する

Zendesk Guide API (ZendeskガイドAPI) は、大規模なコンテンツ管理のための強力なツールを提供します。メディアアップロードの自動化、タグを使用したコンテンツの整理、多言語サポートの構築など、APIは必要なプリミティブを提供します。

ただし、カスタム統合の構築だけが唯一の道ではありません。コードを記述せずに知識ソースを統合したい場合は、eesel AIが代替手段を提供します。AIエージェントはZendesk (ゼンデスク) に接続し、移行を必要とせずに、既存のドキュメントから学習します。

適切な選択は、チームの技術リソースと特定のニーズによって異なります。開発者と独自の要件がある場合は、Guide API (ガイドAPI) が確固たる基盤となります。AI搭載のサポートを迅速に開始したい場合は、eesel AI (イーセルAI) がZendesk (ゼンデスク) のセットアップで何ができるかを探ってください。