コネクションを使用すると、SlackやShopifyなど、サービスやシステムのAPI認証情報を安全に保存できます。コネクションは、ボットビルダーの「APIコールを実行する」ステップでREST APIコールを認証するため、またはオートアシストアクションで使用できます。コネクションを作成するには、管理者であることが必要です。
コネクションについて
コネクションは、以下のAPI認証方法のいずれかでサポートされます。
- APIキー
- 基本認証
- ベアラートークン
- OAuth 2.0
コネクションが格納する認証情報のタイプは、これらの認証方法によって決まります。たとえば、基本認証方式のコネクションでは、ユーザー名とパスワードの情報が格納されます。いったんコネクションを作成すると、あとからその認証方式を変更することはできません。
APIによって、サポートされる認証方法はそれぞれ異なります。APIコールに適した認証方法を決定するには、そのAPIのドキュメントを参照してください。
HTTPヘッダーの認証タイプ
| 認証タイプ | HTTPヘッダー |
|---|---|
| APIキー | コネクションの作成時に設定します。詳しくは「APIキーのHTTPヘッダー」を参照してください。 |
| 基本認証 |
Authorization: Basic
|
| ベアラートークン |
Authorization: Bearer
|
| OAuth 2.0 |
アクセストークンは、Authorization:
Bearer内のサービスに送信されます。
|
ボットでのコネクションの使用について詳しくは、「ボットビルダーでのAPIコールの実行ステップの使用」を参照してください。コネクションの使用について詳しくは、「オートアシストのためのアクションの作成と管理」を参照してください。
OAuthクライアントを作成する
OAuthコネクションには、Slack、Shopify、ZendeskなどのサービスやシステムのOAuth 2.0アクセストークンが格納されています。
OAuth 2.0認証タイプのコネクションを作成する前に、OAuthクライアントを設定する必要があります。OAuthクライアントを設定する際には、外部システムのOAuth設定インターフェイスまたは管理ポータルで提供されるクライアントID、クライアントシークレット、認証URL、トークンURL、およびスコープが必要です。これらの認証情報は、クライアントアプリケーション（Zendeskなど）を外部システムに登録する際に生成されます。正確な手順は外部サービスによって異なります。必要に応じて、クライアントの折り返し電話URLを"https://zis.zendesk.com/api/services/zis/connections/oauth/callback"に設定します。
- 認証コード
- クライアント資格情報
リフレッシュトークンのグラントタイプは、認証コードグラントタイプを使用して作成されたOAuth 2.0クライアントでサポートされています。システムのアクセストークンレスポンスに含まれる expires_in と refresh_token の値が空でない場合、アクセストークンはリフレッシュトークンを使って自動更新されます。
クライアント資格情報のグラントタイプのクライアントで作成されたOAuth 2.0接続には、トークンの有効期限の値が含まれることがあります。このような場合、トークンの有効期限が切れると、同じOAuthクライアントを使用して新しいアクセストークンが取得されます。
OAuthクライアントを作成するには
- 管理センターで、サイドバーにある「
アプリおよびインテグレーション」をクリックし、「コネクション」>「コネクション」を選択します。 - クライアントの名前を入力します。作成したクライアント名は、あとから変更することはできません。
- クライアントIDを入力します。これは、クライアントのユーザー名のように、OAuthクライアントに割り当てられる一意の識別子です。
- クライアントシークレットを入力します。これはクライアントアプリケーションのパスワードの役割を果たし、Zendeskと外部システムとの間の信頼関係を確立します。
- （認証コードグラントタイプのみ）認証URLを入力します。このURLは、認証コードを受け取る際に使用するサーバーのURLです。
- トークンURLを入力します。このURLは、アクセストークンを受け取るために使用するURLです。
- デフォルトのスコープをスペース区切りで入力します。スコープとは、ユーザーに代わってクライアントアプリケーションがアクセスできる対象を表す権限です。
- 「保存」をクリックして、クライアントを作成します。
コネクションを作成する
コネクションは、管理センターの「コネクション」ページで作成できます。
コネクションを作成するには
- 管理センターで、サイドバーにある「 アプリおよびインテグレーション」をクリックし、「コネクション」>「OAuthクライアント」を選択します。
- 「コネクションを作成」をクリックします。
- 認証タイプを選択します。
- コネクションの名前を入力します。作成したコネクションの名前は、あとから変更することはできません。
- 以下のいずれかの操作を行います。
- （APIキー、Basic認証、ベアラートークン）コネクションの認証情報を設定します。コネクションは、この認証情報を使用して、サービスまたはシステムへのREST APIコールを認証します。
- （OAuth 2.0）使用するクライアントを選択し、オプションでスコープをスペース区切りで入力します。スコープを入力しない場合は、OAuthクライアントで指定されたデフォルトのスコープが使用されます。
- コネクションの許可されたドメインを入力します。作成したコネクションの許可されたドメインは、あとから変更することはできません。詳細については、「許可されたドメイン」を参照してください。
- 「保存」をクリックすると、コネクションが作成されます。
コネクションを作成したら、管理センターの「コネクション」ページでその詳細情報を確認できます。詳しくは「コネクションの管理」を参照してください。
許可されたドメイン
コネクションごとに、許可されたドメインとしてURLホスト名の指定が必要です。Zendeskは、APIコールの際にこのホスト名に対してのみコネクションの認証情報を渡します。他のホスト名でコネクションを使用しようとすると失敗します。これは、コネクションの認証情報が誤って漏洩するのを防ぐためです。いったんコネクションを作成すると、あとからその許可されたドメインを変更することはできません。
たとえば、許可されたドメインがapi.example.comのコネクションを使用できるのは、ホスト名がhttps://api.example.comへのAPIコールに対してのみです。
許可されたドメインの要件
コネクションの許可されたドメイン名は128文字以内に制限されます。値内のサブドメインまたはドメイン名は63文字を超えることはできません。値には有効なドメイン名を含める必要があります。
コネクションは常に https スキームを使用します。ftps などの他のスキームはサポートされていません。
許可されたドメインのワイルドカード
コネクションの許可されたドメインでは、オプションでワイルドカード（*）サブドメインを使用できます。これにより、ベアドメインおよび任意のサブドメインでコネクションを使用できます。たとえば、許可されたドメインが *.example.com のコネクションを使用して、example.comまたはexample.comの任意のサブドメインへのAPIコールを認証することができます。
ワイルドカードをサブドメインに使用するには、許可されたドメインの最初の2文字が*.である必要があります。ホスト名の他の部分にワイルドカードを使用することはできません。たとえば、ワイルドカードを使用した exam*.com や my-*.example.com. などのホスト名は許可されません。
また、*.com、*.com.au、*.myshopify.comなどのように、パブリックドメインのサフィックスの部分だけにワイルドカードを使用することもできません。パブリックサフィックスの種類は、publicsuffix.orgのパブリックサフィックスリストで確認できます。
APIキーのHTTPヘッダー
APIキーのコネクションを作成する際には、HTTPヘッダー名を指定する必要があります。このコネクションを使用してAPIコールを実行すると、Zendeskはこのヘッダーの値としてAPIキーを渡します。
APIの多くは、カスタムヘッダーを使用してAPIキーを受け入れます。APIコールに適したヘッダー名については、各APIのドキュメントを参照ください。
ヘッダー名の要件
APIキーコネクションのヘッダー名は、128文字以内に制限されています。ヘッダー名に使用できる文字は、英文字、ハイフン（-）、アンダースコア（_）のみです。
acceptaccept-charsetaccept-encodingaccept-languagecache-controlconnectioncontent-md5cookiedateexpectfromhostif-matchif-modified-sinceif-none-matchif-rangeif-unmodified-sincemax-forwardspragmaproxy-authenticateproxy-authorizationrangeserverreferertetrailertransfer-encodingupgradeuser-agentviawarningwww-authenticate- 以下の文字列から始まるヘッダー名：
x-amz-
x-amzn-x-forwarded-x-zis-