外部サービスと統合するためのコネクションの作成

現在のプランを確認

Suite

すべてのプラン

ファストパス： 管理センター >「アプリおよびインテグレーション」>「コネクション」>「コネクション」

コネクションを使用すると、SlackやShopifyなど、サービスやシステムのAPI認証情報を安全に保存できます。コネクションは、オートアシストアクション内でREST APIコールを認証するために使用できます。コネクションを作成するには、管理者であることが必要です。

メモ：この記事の内容は、旧バージョンのボットビルダーの「APIコールを実行」ステップを使用しているアカウントにも適用されます。

この記事では、次のトピックについて説明します。

• コネクションについて
• コネクションを作成する
• 許可されたドメイン
• APIキーのHTTPヘッダー

コネクションについて

コネクションは、以下のAPI認証方法のいずれかでサポートされます。

• APIキー
• 基本認証
• ベアラートークン
• OAuth 2.0

コネクションが格納する認証情報のタイプは、これらの認証方法によって決まります。たとえば、基本認証方式のコネクションでは、ユーザー名とパスワードの情報が格納されます。いったんコネクションを作成すると、あとからその認証方式を変更することはできません。

APIによって、サポートされる認証方法はそれぞれ異なります。APIコールに適した認証方法を決定するには、そのAPIのドキュメントを参照してください。

HTTPヘッダーの認証タイプ

オートアシストアクション内でコネクションを使用してAPIコールを認証する場合、Zendeskはコネクションの認証情報をHTTPヘッダーに渡します。Zendeskは、コネクションの認証タイプに基づいてこのヘッダーを決定します。

認証タイプ	HTTPヘッダー
APIキー	コネクションの作成時に設定します。詳しくは「APIキーのHTTPヘッダー」を参照してください。
基本認証	Authorization: Basic
ベアラートークン	Authorization: Bearer
OAuth 2.0	アクセストークンは、Authorization: Bearer内のサービスに送信されます。

コネクションの使用について詳しくは、「オートアシストのためのアクションの作成と管理」を参照してください。

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"に設定します。

メモ：Zendeskは、OAuth 2.0 Authorization Frameworkに準拠した外部システムとの接続のみをサポートしています。

以下のOAuth 2.0グラントタイプ使用してOAuthクライアントを作成できます。

• 認証コード
• クライアント資格情報

リフレッシュトークンのグラントタイプは、認証コードグラントタイプを使用して作成されたOAuth 2.0クライアントでサポートされています。システムのアクセストークンレスポンスに含まれる expires_in と refresh_token の値が空でない場合、アクセストークンはリフレッシュトークンを使って自動更新されます。

クライアント資格情報のグラントタイプのクライアントで作成されたOAuth 2.0接続には、トークンの有効期限の値が含まれることがあります。このような場合、トークンの有効期限が切れると、同じOAuthクライアントを使用して新しいアクセストークンが取得されます。

メモ：場合によっては、1つのリフレッシュトークンでアクセストークンが複数回リフレッシュされることがあります。システムによってはリフレッシュトークンの再利用を防ぐ仕組みが実装されているため、可能であれば猶予期間を設けるか、代わりにクライアント認証情報のグラントタイプを使用することをお勧めします。

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

1. 管理センターで、サイドバーにある「 アプリおよびインテグレーション」をクリックし、「コネクション」>「コネクション」を選択します。
2. クライアントの名前を入力します。作成したクライアント名は、あとから変更することはできません。
3. クライアントIDを入力します。これは、クライアントのユーザー名のように、OAuthクライアントに割り当てられる一意の識別子です。
4. クライアントシークレットを入力します。これはクライアントアプリケーションのパスワードの役割を果たし、Zendeskと外部システムとの間の信頼関係を確立します。
5. （認証コードグラントタイプのみ）認証URLを入力します。このURLは、認証コードを受け取る際に使用するサーバーのURLです。
6. トークンURLを入力します。このURLは、アクセストークンを受け取るために使用するURLです。
7. デフォルトのスコープをスペース区切りで入力します。スコープとは、ユーザーに代わってクライアントアプリケーションがアクセスできる対象を表す権限です。
8. 「保存」をクリックして、クライアントを作成します。

コネクションを作成する

コネクションは、管理センターの「コネクション」ページで作成できます。

コネクションを作成するには

1. 管理センターで、サイドバーにある「 アプリおよびインテグレーション」をクリックし、「コネクション」>「OAuthクライアント」を選択します。
2. 「コネクションを作成」をクリックします。
3. 認証タイプを選択します。
4. コネクションの名前を入力します。作成したコネクションの名前は、あとから変更することはできません。
5. 以下のいずれかの操作を行います。
   • （APIキー、Basic認証、ベアラートークン）コネクションの認証情報を設定します。コネクションは、この認証情報を使用して、サービスまたはシステムへのREST APIコールを認証します。
   • （OAuth 2.0）使用するクライアントを選択し、オプションでスコープをスペース区切りで入力します。スコープを入力しない場合は、OAuthクライアントで指定されたデフォルトのスコープが使用されます。
6. コネクションの許可されたドメインを入力します。作成したコネクションの許可されたドメインは、あとから変更することはできません。詳細については、「許可されたドメイン」を参照してください。
7. 「保存」をクリックすると、コネクションが作成されます。

コネクションを作成したら、管理センターの「コネクション」ページでその詳細情報を確認できます。詳しくは「コネクションの管理」を参照してください。

メモ：OAuth 2.0認証タイプでコネクションを作成した場合、コネクションの作成時に定義したスコープではなく、外部システムのアクセストークンレスポンスに含まれるスコープが保存されます。この値は255文字を超えることはできません。

許可されたドメイン

コネクションごとに、許可されたドメインとして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文字以内に制限されています。ヘッダー名に使用できる文字は、英文字、ハイフン（-）、アンダースコア（_）のみです。

以下のHTTPヘッダー名は使用できません。

• accept
• accept-charset
• accept-encoding
• accept-language
• cache-control
• connection
• content-md5
• cookie
• date
• expect
• from
• host
• if-match
• if-modified-since
• if-none-match
• if-range
• if-unmodified-since
• max-forwards
• pragma
• proxy-authenticate
• proxy-authorization
• range
• server
• referer
• te
• trailer
• transfer-encoding
• upgrade
• user-agent
• via
• warning
• www-authenticate
• 以下の文字列から始まるヘッダー名：
  • x-amz-
  • x-amzn-
  • x-forwarded-
  • x-zis-