Zendeskアプリを構築している場合、最終的にはAPIリクエストを行う必要が出てくるでしょう。外部サービスからデータを取得したり、プログラムでチケットを作成したり、別のプラットフォームと統合したりするかもしれません。ZendeskアプリリクエストAPIは、これを行うためのいくつかの方法を提供しますが、ドキュメントが複数のページに分散しており、認証オプションが混乱する可能性があります。
このガイドでは、ZendeskアプリからAPIリクエストを行うために知っておくべきことをすべてまとめています。ZAF Client (Zendesk Apps Framework) の request() メソッド、Requests APIエンドポイント、認証戦略、および開発者が遭遇する一般的な落とし穴について説明します。カスタムコードを書かずにZendeskワークフローを自動化するより簡単な方法をお探しの場合は、eesel AIがZendeskと統合してAIエージェントを通じてチケット管理を処理する方法についても触れます。
ZendeskアプリリクエストAPIとは？
開発者が「ZendeskアプリリクエストAPI」を検索するとき、通常は次の2つのうちの1つを探しています。
- ZAF Client (Zendesk Apps Framework) の
request()メソッド - Zendeskアプリが外部APIまたはZendesk API自体にHTTPリクエストを行うことができるJavaScript関数 - Requests APIエンドポイント - エンドユーザーが自分の視点からチケットを作成および表示できるREST API
ZAF request() メソッドは、Zendesk内で実行されるアプリを構築するときに使用します。認証を処理し、クロスドメイン制限を回避し、ブラウザ環境から安全なAPI呼び出しを行う複雑さを管理します。Requests APIは、顧客に完全なエージェントアクセス権を与えずにチケットを送信させたいときに呼び出します。
それぞれがどのように機能し、いつ使用するかを詳しく見ていきましょう。
ZAF Client (Zendesk Apps Framework) の request() メソッドについて
Zendesk Apps Framework (ZAF)は、アプリ内で実行されるJavaScriptクライアントを提供します。client.request()メソッドは、Zendesk環境内からHTTPリクエストを行うためのゲートウェイです。
これが存在する理由は次のとおりです。ブラウザはセキュリティ上の理由からクロスオリジンリクエストをブロックします。アプリが外部APIを直接呼び出そうとすると、CORSエラーが発生します。ZAFは、リクエストをZendeskプロキシサーバー経由でルーティングすることでこれを解決します。プロキシは実際のリクエストを行い、応答をアプリに返します。
request()メソッドはJavaScript Promiseを返すため、.then()またはasync/awaitで応答を処理します。
const client = ZAFClient.init();
client.request({
url: 'https://api.example.com/data',
type: 'GET',
headers: {
'Authorization': 'Bearer {{setting.api_token}}'
}
}).then(data => {
console.log('Response:', data);
}).catch(error => {
console.error('Error:', error);
});
request()メソッドの主な機能：
- プロキシサーバーのルーティング - リクエストをサーバー側で行うことでCORSを回避
- セキュアな設定 - manifest.jsonプレースホルダーを使用して、APIキーをブラウザの開発者ツールから隠します
- OAuthトークンの管理 - トークンを公開せずにサードパーティのOAuthフローを処理
- JWTエンコーディング - セキュリティを強化するために、JSON Web Tokenでリクエストに署名
注意すべき制限事項の1つ：request()メソッドはバイナリファイルのアップロードをサポートしていません。ファイルを添付する必要がある場合は、別のアプローチを使用する必要があります（これについては後で詳しく説明します）。
Zendeskアプリリクエストの認証方法
認証は、ほとんどの開発者が行き詰まる場所です。Zendeskは複数の認証方法を提供しており、適切な方法を選択するかどうかは、何をしようとしているかによって異なります。
APIトークンを使用したBasic認証
Zendesk API自体を呼び出すための最も簡単なアプローチ。資格情報を{email}/token:{api_token}としてフォーマットし、base64でエンコードして、Authorizationヘッダーに「Basic 」プレフィックスを付けて含めます。
const credentials = btoa('agent@company.com/token:abc123xyz');
const authHeader = `Basic ${credentials}`;
よくある間違い：「Basic 」プレフィックスを忘れること。ヘッダーは「Basic 」で始まり、その後にスペース、そしてbase64エンコードされた文字列が続いている必要があります。多くの開発者は資格情報を正しくエンコードしますが、プレフィックスを省略するため、401 Unauthorizedエラーが発生します。
セキュアな設定
サードパーティAPIを呼び出している場合、APIキーをJavaScriptに公開したくありません。誰でもブラウザコンソールでそれらを見ることができます。セキュアな設定は、機密データをサーバー側に保存することでこれを解決します。
manifest.jsonで：
{
"parameters": [
{
"name": "api_token",
"type": "text",
"secure": true
}
],
"domainWhitelist": ["api.example.com"]
}
二重中括弧を使用してコードで設定を参照します。
headers: {
'Authorization': 'Bearer {{setting.api_token}}'
}
実際のトークン値はZendeskのサーバーに保存され、リクエスト時に挿入されます。ユーザーはアプリのインストール中にそれを構成し、ブラウザに公開されることはありません。
OAuth 2.0
Salesforce、Slack、Googleなどのサービスとの統合の場合、OAuthが標準です。ZAFは認証コードフローをサポートしています。
- アプリはユーザーをOAuthプロバイダーにリダイレクトします
- ユーザーはアクセスを承認します
- プロバイダーは認証コードでリダイレクトバックします
- アプリはコードをアクセストークンと交換します
- ZAFはトークンを安全に保存し、自動的に更新します
セットアップには、OAuthプロバイダーにアプリを登録し、リダイレクトURLを構成する必要があります。セットアップが完了すると、トークン管理は自動的に処理されます。
JWTトークン
署名付きリクエストの場合、ZAFはHS256アルゴリズムを使用したJWTエンコーディングをサポートしています。秘密鍵を提供すると、ZAFは有効期限などのクレームを含むトークンを生成します。これは、リクエストがZendeskアプリから送信され、改ざんされていないことを確認する必要がある場合に役立ちます。
ブラウザCookie認証
アプリ内からZendesk APIを呼び出す場合、明示的な認証を完全にスキップできます。ZAFクライアントは、ブラウザのZendeskセッションCookieを自動的に使用してリクエストを認証します。これは、外部APIではなく、Zendesk APIエンドポイントでのみ機能します。
どの認証方法を使用する必要がありますか？
| シナリオ | 推奨される方法 |
|---|---|
| アプリからZendesk APIを呼び出す | ブラウザCookie（自動） |
| 外部コードからZendesk APIを呼び出す | APIトークンを使用したBasic認証 |
| サードパーティAPIを呼び出す | セキュアな設定またはOAuth |
| 署名/検証済みリクエストが必要 | JWT |
Zendesk APIの操作の詳細については、ZendeskチケットAPIに関するガイドをご覧ください。
サードパーティAPIへのリクエストの作成
デフォルトでは、ZAFはリクエストをプロキシサーバー経由でルーティングします。これは、corsオプションによって制御されます。
// デフォルトの動作 - プロキシを使用 (cors: false)
client.request({
url: 'https://api.example.com/data',
type: 'GET'
});
// 直接リクエスト - APIでCORSサポートが必要
client.request({
url: 'https://api.example.com/data',
type: 'GET',
cors: true
});
プロキシのアプローチは任意のAPIで動作しますが、遅延が追加されます。直接リクエストは高速ですが、APIがCORSヘッダーをサポートしている必要があります。ほとんどのプロダクションアプリは、信頼性のためにプロキシを使用します。
セキュアな設定を使用して外部APIからデータをフェッチする完全な動作例を次に示します。
const client = ZAFClient.init();
async function fetchCustomerData(customerId) {
try {
const response = await client.request({
url: `https://api.example.com/customers/${customerId}`,
type: 'GET',
headers: {
'Authorization': 'Bearer {{setting.api_key}}',
'Content-Type': 'application/json'
}
});
return response;
} catch (error) {
console.error('Failed to fetch customer:', error);
throw error;
}
}
エラー処理は重要です。リクエストが失敗した場合、Promiseは拒否されるため、常にtry/catchで呼び出しをラップするか、.catch()を使用します。
Zendesk Requests APIの操作
Requests APIは、ZAF request()メソッドとは異なります。これは、エンドユーザー（顧客）が自分の視点からチケットを操作できるREST APIエンドポイントです。
Tickets APIとの主な違い：
- エンドユーザービュー - 公開コメントとユーザーがアクセスできるフィールドのみを表示
- 匿名サポート - 認証なしで呼び出すことができます（レート制限あり）
- 簡略化された権限 - エージェントの資格情報は不要
一般的なエンドポイント：
| エンドポイント | メソッド | 説明 |
|---|---|---|
/api/v2/requests | GET | 認証済みユーザーのリクエストを一覧表示 |
/api/v2/requests | POST | 新しいリクエスト（チケット）を作成 |
/api/v2/requests/{id} | GET | 特定のリクエストの詳細を取得 |
/api/v2/requests/{id} | PUT | 既存のリクエストを更新 |
リクエストの作成：
curl https://company.zendesk.com/api/v2/requests.json \
-d '{"request": {"subject": "Help needed", "comment": {"body": "I have a question"}}}' \
-H "Content-Type: application/json" \
-X POST
認証済みリクエストの場合は、Authorizationヘッダーを含めます。匿名リクエスト（お問い合わせフォームなど）の場合は、認証を省略します。匿名リクエストは、トライアルアカウントの場合、1時間あたり5回にレート制限されます。
チケットを作成する統合を構築している場合は、APIを使用してZendeskチケットを作成するに関するガイドも役立つ場合があります。
一般的なエラーとトラブルシューティング
優れたドキュメントがあっても、うまくいかないことがあります。開発者が遭遇する最も一般的な問題を次に示します。
401 Unauthorized
認証ヘッダーの形式が正しくありません。再確認してください。
- 「Basic 」プレフィックスが存在する（その後にスペースがある）
- 資格情報が正しくbase64エンコードされている
- メール形式が
{email}/token:{api_token}である（「/token」サフィックスに注意） - APIトークンがアクティブであり、期限切れになっていない
CORSエラー
CORSをサポートしていないAPIに直接リクエストを送信しようとしています。cors: trueを省略してプロキシを有効にするか、APIプロバイダーにCORSヘッダーを追加するように依頼してください。
429 Rate Limit Exceeded
Zendeskには複数のレート制限があります。アプリには独自の制限（通常は1分あたり100リクエスト）があり、アカウントには別の制限（ほとんどのエンドポイントで1分あたり700リクエスト）があります。429が発生した場合は、Retry-Afterヘッダーを確認し、再試行するまで待ってください。詳細については、公式のレート制限ドキュメントを参照してください。
422 Unprocessable Entity
JSONの形式が正しくありません。一般的な原因：
- プロパティ名を囲む引用符がない
- オブジェクト内の末尾のカンマ
- 二重引用符ではなく単一引用符
- 無効なエスケープシーケンス
ファイルアップロードの問題
ZAF request()メソッドはバイナリアップロードをサポートしていません。回避策は次のとおりです。
- アップロードを処理するために別のサーバーを使用する
- ファイルをbase64としてエンコードし、サーバー側でデコードする
- バイナリ処理にRestSharpなどのライブラリを使用する
統合の例については、サードパーティアプリを使用してZendeskをSlackに接続する方法に関するガイドを参照してください。
コードなしでZendeskアプリの統合を構築する
カスタムAPI統合の構築と維持には時間がかかります。認証、エラー再試行ロジック、レート制限、およびAPIの変更に伴う継続的なメンテナンスを処理する必要があります。
目標がカスタムアプリを構築するのではなく、チケットワークフローを自動化することである場合は、実際にコードを記述する必要があるかどうかを検討してください。Zendesk用のAIエージェントは、開発作業なしでチケットの作成、ルーティング、および応答を処理します。
違いは次のとおりです。APIアプローチでは、人間が応答する必要があるチケットを移動するためのスクリプトを作成しています。AIエージェントを使用すると、ビジネスを理解し、チケットライフサイクル全体を処理するようにシステムをトレーニングしています。Zendeskアカウントに接続すると、過去のチケット、ヘルプセンターの記事、およびマクロから学習します。
プログレッシブロールアウトモデルは、AIがレビュー用の応答を下書きすることから始め、それが証明されるにつれて完全な自動化に拡張することを意味します。API呼び出しを自動化するだけでなく、チケット量を削減しようとしているチームにとって、これは多くの場合、カスタム開発よりも迅速な結果をもたらします。
よくある質問
Share this article
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.
