Zendesk APIの管理者ガイド

Zendesk APIとは？

API（アプリケーションプログラミングインターフェイス）は、ソフトウェアアプリケーション用のツールです。レストランでは、ウェイターがキッチンからテーブルに料理を運びます。APIも同様の仕事をします。あるポイントから別のポイントへデータを運びます。APIでは、料理は「リソース」と呼ばれ、それを運ぶウェイターは「エンドポイント」と呼ばれます。レストランで注文されるような料理を考えてみましょう。エンドポイントによっては、盛り合わせ料理のようなアイテムのコレクションを返してくるものがあります。このAPIの例として、List Usersエンドポイントがあります。これは、Zendeskサポートアカウント内のすべてのユーザーのリストを返します。一方、Show Userエンドポイントなどのエンドポイントのように、特定のものに焦点を合わせ、1つだけを返すAPIもあります。

また、APIを使用してZendeskの処理を改変することもできます。たとえば、ステーキの調理方法をウェイターに伝えるとします。シェフは実際にステーキをあなたに合わせて調理します。APIは、Zendeskユーザーの多くが使用している強力なリソースです。リソースの一括インポート、アプリの作成、外部ソースへのデータ提供などを行うために使用できます。

Zendesk APIのリファレンスドキュメントのほとんどは、Zendesk開発者ポータルのAPIリファレンスセクションにあります。リファレンスドキュメントには、利用可能なすべてのエンドポイントが記載されています。 また、Zendesk開発者ガイドを参考にすることもできます。このドキュメントはAPIに関する包括的な内容を提供しますが、この記事ではAPIをデコードして使用する方法について説明します。

APIを使用する理由

APIが何であれ「なぜ気に留める必要があるのか​​？」とお考えになるかもしれません。 簡単に言えば、APIを使用すれば、UIで（ネイティブまたはプランレベルで）使用できない機能を、すべて手作業で行うよりもはるかに短い時間で追加できます。

現在、EssentialまたはTeamプランのアカウントお持ちの場合、APIを使用すると、Professionalにアップグレードせずにデータを直接エクスポートすることができます（データの自動エクスポートが可能）。同様に、APIを使用してレポート用にチケットデータを取得できます。APIはチケットに関連するすべての情報を返すことができるため、APIからの出力を介してサードパーティのレポートアプリケーションにデータを渡すことができます。

多くのレコードを迅速に更新できることは、APIを使用するもう1つの利点です。たとえば、エージェントインターフェイスでは一度に1つの組織しか作成できませんが、APIを使用すると一度に最大100の組織を作成できます。同様に、一度に更新できるアイテムの最大数もAPIの方が高くなっています。インターフェイスでは、一度に編集できるのは60チケットまでですが、APIでは最大100チケットの編集が可能です。

その他の一般的なタスクとしては、次のようなものがあります。

• チケットを作成する
• 別のシステムからZendeskへチケットデータを移行する
• ユーザーを一括編集する
• レコードを検索する
• 他にもたくさんのタスクがあります

APIを使用する理由は以上です。次はAPIリクエストの作成方法を説明します。

フォーマット

Zendesk APIは、JSONと呼ばれる軽量フォーマットでデータを返します。詳細については、Zendeskヘルプセンターの「JSONの操作」を参照してください。ChromeまたはFirefox用のJSONビューアー拡張機能をインストールすることにより、フォーマットされたデータをWebブラウザで表示できます。

JSONは次のようになります。

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
  ]
}

エンドポイントの典型的な例は次のようになります。

subdomain.zendesk.com/api/v2/users/me.json

エンドポイントは次のアクションを実行できます。

• GET：アイテムの取得 
• POST：これまでになかったアイテムの作成
• PUT：既存のアイテムの更新
• DELETE：アイテムの削除

ブラウザで実行できるのは、GETリクエストのみです。その他のアクションは、cURLやPostmanなどのツールを使用することで実行できます。

cURL

リファレンスドキュメントでは、すべてのエンドポイントの例でcURLを使用しています。cURLは、ブラウザなしでAPIコマンドを試せるコマンドラインツールです。詳細については、Zendeskヘルプセンターの「cURLのインストールと使用」の記事を参照してください。4種類のAPIコールのいずれにもcURLを使用できます。Macにはプリインストールされていますが、Windowsではインストールする必要があります。手順については、Zendeskヘルプセンターの「cURLのインストール」の記事を参照してください。

リクエストのステータス

APIリクエストを行うたびに、それが機能したかどうかを知らせる通知を受け取ります。リクエストが機能しなかった場合は、その原因の手がかりがレスポンスで提供されます。これらの応答は「ステータスコード」と呼ばれます。基本的なステータスコードには次の種類があります。

• 200：リクエストは成功しました
• 400：リクエストは失敗しました
• 409：結合または制約エラー、コールを再試行
• 422：処理できないエンティティ
• 429：レート制限を超えました
• 500：警告または一時的な状態、解決されない場合はサポートに連絡してください

ステータスコードの詳細については、APIドキュメントの「レスポンスフォーマット」をご覧ください

演習

APIの基本に関する説明は以上です。次は、実際に使用してチケットを検索してみましょう。

私がTeamプランのユーザーであり、チケットがさまざまなレベルのサポートにエスカレートされるタイミングを追跡するためにタグを使用しているとします。この場合、追加するタグはescalation_oneとescalation_twoです。

ここで、両方のエスカレーションが発生したことのあるシステム内のすべてのチケットについてレポートを生成したいとします。これらのチケットを返すためのビューを作成しようとしましたが、アーカイブされたチケットが表示されなかったため、これは私のニーズを満たしませんでした。どうしたらよいでしょうか？

回答：APIを使用してチケットを取得する方法があります。

これを行うには、Search APIエンドポイントをチェックアウトする必要があります。このエンドポイントはアーカイブされたチケットを除外しないので、これを使用すれば、これら2つのタグを含むすべてのチケットのリストを返すことができます。同様に、Search APIは単純なGETコールです。したがって、ブラウザの別のタブでZendesk Supportにサインインすれば、このエンドポイントをブラウザで直接使用することができます。Searchエンドポイントのフォーマットは次のとおりです。

subdomain.zendesk.com/api/v2/search.json?query={search_string}

重要：「subdomain」は、ご使用のアカウントのサブドメインに置き換えてください。

Search APIは非常に柔軟性があり、クエリには「Zendesk Searchリファレンス」に記載されているキーワードや値、演算子なら何でも使用できます。この例では、単にタグを探しているだけなので、検索文字列で使用するパラメータは「tags」のみです。複数のタグを検索する場合は、「tags」パラメータの後に指定する複数のタグをカンマで区切るだけです。コールは次のようになります。

https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two

リクエストを認証するには、エージェントまたは管理者の資格を持ち、ブラウザの別のタブでZendeskサポートにサインインしていることを確認してください。

ブラウザでこのコールを実行すると、これらのタグの両方を含むチケットのリストが返されます。あとは、JSON出力を将来使用するために保存するだけです。

おめでとうございます！これで演習は終わりです！APIは、多くの用途を備えた強力なツールです。さらに詳しい知識を得るには、「リファレンスドキュメント」と「Zendesk開発者ドキュメント」をお読みください。