AlteryxからZendesk APIを使ってGuideの記事を取得してみた

2023.02.28

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、まつおかです。

今回はAlteryxからZendeskのAPIを使ってZendesk Guideに登録している記事の一覧を取得してみましたので、その手順をご紹介します。

使用環境

検証に使用した環境は以下の通りです。

  • Windows 10 Pro
  • Alteryx Designer 2022.1
  • Zendesk Guide Enterpriseプラン

Zendesk API

Zendesk Guide の記事は Zendesk Help Center API を使用して取得することができます。

今回APIリクエストの認証には APIトークン認証 を使用しています。 トークンはZendesk管理センターのアプリおよびインテグレーション > API > Zendesk APIの設定タブにあるトークンアクセスを有効にし「APIトークンを追加」ボタンをクリックすることで発行できます。(発行は管理者アカウントのみ)

AlteryxからZendesk APIを実行

今回作成したワークフローはこちらです。

処理の大まかな流れとしては、リクエストに必要な情報を生成してからAPIを実行し、取得したデータを整形するといったものになります。

それぞれの詳細を説明していきます。

リクエストに必要な情報の生成

APIのリクエストには、エンドポイントと認証情報が必要になります。

▼エンドポイント

Guideの記事を取得する際のエンドポイントについてはこちらをご参照ください。

記事を取得したいGuideページでは カテゴリとセクションを使用しコンテンツを分けています。階層は以下のようなイメージになっています。

今回は特定のカテゴリのみの情報を取得したかったので、以下のエンドポイントを使用しました。

https://<サブドメイン>.zendesk.com/api/v2/help_center/categories/<category_id>/articles

category_id は、対象カテゴリのURLで確認が可能です。

また、上記のエンドポイントから取得できるデータでは、各記事がどのセクションに入っているかの情報が section_id しかないため、以下のエンドポイントを使用しセクションの情報も取得しました。

https://<サブドメイン>.zendesk.com/api/v2/help_center/categories/<category_id>/sections

▼認証情報

APIトークンを使用した認証の場合、メールアドレスとトークンを組み合わた <メールアドレス>/<トークン> の形式でBase-64エンコードされた情報が必要になります。この情報はヘッダーで指定します。

Authorization: Basic {base-64-encoded email_address/token:api_token}

エンドポイント情報とエンコードした認証情報を結合するまでの処理を行っているのが最初のこちらのフローになります。

①エンドポイント

per_pageは一度に取得できるリストの数を指定するため列として用意しています。デフォルトは30なので、指定可能な最大値の100を設定しています。今回は記事の数が100以下なのでこの指定で一度で取得できますが、100を超える場合はリストのページが分かれてしまいますので別途繰り返し処理を追加する必要がありますが、今回その説明は割愛します。
ページネーションについてはこちらを参照ください。

②認証情報

<メールアドレス>/<トークン>が入っています。認証情報はヘッダーに「Authorization」という名前で設定しますので、列名を「Authorization」にしておきます。

③Base64エンコード

Base64エンコーダーツールを使用し、認証情報をエンコードします。 エンコードした結果は「Base64_encoded」というフィールドに出力されます。

④ヘッダ情報生成

エンコードした認証情報の頭に「Basic 」を付与します。

最後、エンドポイントに認証情報を付加した状態がこちらです。

APIの実行

次にダウンロードツールを使ってAPI実行時の設定をします。

基本情報タブではURLにエンドポイントの入ったURLフィールドを、ヘッダータブでは認証情報の入ったAuthorizationフィールドを、ペイロードタブではHTTPアクションでGETを選択し、「これらのフィールドからの値」でper_pageフィールドを指定します。

データを整形し不要な行を除外

ダウンロードツールで取得したデータは「DownloadData」フィールドにJSON形式で入ってきますので、JSONパースツールを使用しテーブル形式に変換します。

「JSON_Name」にキーの名前が、「JSON_ValueString」に各キーに対応する文字列が入ります。

JSON_Nameの中で「sections」で始まるものがセクション情報、「articles」で始まるものが記事情報となりますが、それ以外の行は今回不要となりますので、次のフィルターツールで除外します。

データIDとプロパティを分割

JSON_NameにはデータIDとプロパティが連結された状態なので、フォーミュラツールで正規表現を使い分割します。

セクションと記事に分け、横持ち変換後結合

セクション情報と記事情報をフィルターで振り分け、クロスタブツールを使用し縦持ちになっているデータを横持ちに変換します。先程分割したIndexが同じセクションや記事のひとかたまりですので、グループ化にはそれぞれIndexを指定します。
また、変換後のフィールドサイズはデフォルトで2048となっていますが、記事は文字数が多くデフォルト値を超過することがあります。フィールドサイズを超えた文字は切り落とされてしまいますので、適切なサイズを指定してください。

変換後はこのようになります。(articlesの場合)

次に結合ツールを使い記事とセクション情報を紐付けます。結合時のキーは記事側が「section_id」、セクション側は「id」となります。

最後に不要な列を除外して、出力後そのままでも見やすいようにセクション名でソートして出力しました。

さいごに

以上がZendesk APIを使用し記事を取得、加工する一連の流れとなります。

APIで取得できるデータや構造は様々ですが、他のAPIを使用する場合でも今回ご紹介したフローを応用させることで取得から加工が楽にできるのではないかと思いますのでぜひ参考にしてください!