Chat APIチュートリアル：OAuthトークンの生成（Chatの統合アカウント）

Support + ChatアカウントとPhase 4 ChatアカウントでChat APIを使用するには、APIリクエストを認証するためにOAuthアクセストークンを生成する必要があります。基本認証はサポートされていません。ただし、初めてトークンを生成するのは少し混乱することがあるので、このチュートリアルでは、手動でトークンを生成する方法をステップバイステップで例示して解説します。このチュートリアルを終えれば、Chat APIリクエストでデータの読み書きに使用できるトークンが生成できているでしょう。

アプリケーションを構築している場合は、プロセスを自動化するために、そのアプリにトークン生成機能を追加することをお勧めします。

Chat APIのアクセストークンを生成するには2つの方法があります。テスト環境では手短で簡便な方法として「インプリシット」グラントフローを使用します。本番環境ではやや手間のかかる正式な方法として「認証コード」グラントフローを使用します。このチュートリアルでは、どちらの方法も説明します。

条件

このチュートリアルは、上記の記事で参照した変更をすべて適用したChatの統合アカウントを対象としています。現在これらの変更のロールアウトが少しずつ進められているため、一部のアカウントでは他のアカウントよりも先に変更が必要になる場合があります。ご自身のアカウントがすべての変更を受けているかどうか不明な場合は、サポートチームにお気軽にお問い合わせください。

メモ：アカウントへの変更に伴い、OAuthトークンを再生成する必要があります。アカウントが変更を受ける前にこのチュートリアルを完了した場合は、その変更後にもう一度トークン生成の手順を実行する必要があります。

手順

OAuthの「インプリシット」グラントフローは、以下の手順で行います。

1. OAuth APIクライアントを作成する
2. 手順1で得た情報を使用して、トークンを取得するためのOAuthインプリシットグラントフローを実行する

OAuth APIクライアントを作成する

まずはAPIクライアントが必要です。「Zendesk Chat」>「アカウント」>「API & SDKs」にアクセスし、「APIクライアントを追加」ボタンをクリックします。任意のクライアント名と会社名を入力し、リダイレクトURLに http://localhost:8080 と入力します。次の画面のように表示されます。

この状態で「APIクライアントを作成」をクリックすれば、設定は終了です。クライアントIDとシークレットを含むポップアップが表示されます。重要：クライアントシークレットは一度しか表示されないため、後で使用するためにメモしておきます。次の画面のようなポップアップです。

これでAPIクライアントの準備ができたので、クライアントIDとクライアントシークレットをメモして、「OK」をクリックしてください。これでOAuthのグラントフローを実行する準備が整いました。

トークンを取得するためのOAuthインプリシットグラントフローを実行する

このアプローチでは、OAuthインプリシットグラントフローを使用します。別のアプローチとして、OAuth「認証コード」グラントフローを使用することもできます（次のセクションで説明）。手動で行う場合は、この「インプリシット」型のアプローチの方がステップ数が少なく、後述の認証コードグラントフローよりも簡便です。

1. 上述の「OAuth APIクライアントを作成する」の手順に従います。

2. OAuthクライアントから以下の情報を収集します。

• クライアントID：CLIENT_ID
• ご利用のZendeskサブドメイン

3. 以下のURLをご自分のCLIENT_IDとZendeskサブドメインでフォーマットし、新しいブラウザタブに貼り付け、Enterキーを押します。

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

注意事項：

• Chat OAuthクライアントのリダイレクトURLの値が1つしかない場合、redirect_uriの値を渡すことは省略できます。システムはデフォルトでOAuthクライアントのリダイレクトURLを1つ使用するからです。
• OAuthクライアントのリダイレクトURLが複数ある場合は、redirect_uriを渡す必要があります。redirect_uriを渡した場合は、URLエンコードされている必要があります。上記の例では、オプションのリダイレクトパラメータは次のようになります：redirect_uri=http%3A%2F%2Flocalhost%3A8080

4. コールが行われ、ログインして「許可」を選択してトークンを生成するよう求められます。

コールが成功すると、ブラウザのアドレスフィールドに新しいOAuthトークンが表示されます（access_tokenの値として返されます）。

ブラウザのメインウィンドウにエラーメッセージが表示されたように見えても、'access_token' がブラウザのURLフィールドに返されていれば、コールは成功です。

ワークフローのデモを以下に示します。

 

もう1つのトークン生成法（やや時間がかかる）

この手順では、前のセクションと同様にトークンを生成しますが、OAuthの「認証コード」グラントフローを実演します。OAuthクライアントの情報をメモしておきます。これは以下の手順で使用します。

ここでは実際のデータの代わりにプレースホルダを使用します。実際のOAuthクライアントのシークレットはChatアカウントのパスワードであるため、取り扱いの際は万全のセキュリティで保護してください。

• クライアントID：CLIENT_ID
• クライアントシークレット：CLIENT_SECRET
• リダイレクト先URI: http://localhost:8080
• サブドメイン：Zendeskのサブドメイン。アカウントが niall.zendesk.com の場合、niall がサブドメインの部分になります。
• 認証コード：まだ取得していません

1. 最初のURLを用意する

ここでは、認証コードを要求するためのURLを作成します。https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new にアクセスし、上記の情報を渡すためのクエリパラメータを追加する必要があります。今回必要な情報は以下のとおりです。

• response_type：これは常に code です。
• redirect_uri：アクセスを許可した後にリダイレクトされる場所。このチュートリアルでは http://localhost:8080 です。
• client_id：すでに説明したように、あなた自身の固有IDです。
• scope： このトークンに付与するアクセス権限。read と write を選択します。
  • また、Chat Conversations APIに対してトークンを使用する場合には、'chat' スコープも含めます。
• subdomain：お使いのZendeskサブドメインです。

これらをすべてURLにエンコードすると、最終的なURLは次のようになります。

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

CLIENT_ID と SUBDOMAIN の箇所だけが、実際のURLと異なる部分となります。

2. cURLコールを準備する

実際にそのURLにアクセスする前に、アクセスの後に実行するcURLコールを作成してみましょう。今回必要な情報は以下のとおりです。

• grant_type：これは常に authorization_code です。
• code：これはURLからのアクセスを許可した後に取得されます。
• client_id：クライアントID
• client_secret：クライアントシークレット
• redirect_uri：さきほどの手順と同じく http://localhost:8080
• scope：さきほどの手順と同じく read および write

これらをすべてまとめると、次のようなコマンドになります。

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

注意：CLIENT_ID と CLIENT_SECRET は既にあるはずですが、AUTH_CODE はまだありません。

3. 認証コードを取得する

次に、手順1で作成したURLを実行してみると、以下のようなページが表示されます。

「許可する」をクリックしてアクセス許可すると、リダイレクトURLにリダイレクトされます。エラーページのように見えますが、ここで重要なのは返されたURLの中にある認証コード（?code= 以降の文字列）です。

そのコードをコピーして、最後の手順の準備をしましょう。認証コードは短い時間しか有効ではありません。数分以上待つ場合は、上記の手順を再度実行して、新しいコードを取得する必要があります。

4. cURLコールを実行してトークンを取得する

手順2で構築したcURLコールは次のようなものでした。

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

AUTH_CODE を手順3のコードに置き換えて、ターミナルアプリケーションからコマンドを実行します。以下のようなJSONオブジェクトが返されます。

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5. 新しいトークンをテストする

期待どおりに動作したかどうかを確認するために、テストを行うのは常に推奨されることです。最も簡単な方法は、GET コマンドを /api/v2/chats に送信してアカウント情報を確認することです。

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

TOKEN を手順4で取得した情報に置き換えます。 

追加情報

機密性の高いclient_type

前の2つのセクションで、「インプリシット」と「認証コード」の2種類のグラントについて説明しましたが、Chat APIは、クライアント認証情報を使用した機密クライアント向けグラントタイプもサポートしています。これらについては、リファレンスドキュメントの「Confidential grant types」で詳しく説明しています。

管理者やエージェントがメトリックのレポート作成などでAPIコールを行う場合は、機密クライアント向けグラントタイプを使用してOAuthトークンを取得することをお勧めします。client_type を「confidential」に設定する必要があります。デフォルトではこの値は「public」に設定されています。これはAPIを介してのみ行うことができ、以下の手順で達成することができます。

1. クライアントIDを取得する

まず、新しいクライアントのIDが必要です。これは新しいトークンを使って、次のようなコールで取得できます。

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

これですべてのクライアントが表示されます。クライアントは1つしかないかもしれませんが、クライアントが多い場合は、更新したいクライアントを選び、そのIDをメモしておいてください。

2. client_typeを更新する

これでクライアントのIDがわかったので、次のcURLコールを実行して client_type プロパティを更新します。

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

これが完了すると、制限されたエンドポイントでトークンを使用することができます。