別サイトで2014/4/23に投稿した記事です。別サイト閉鎖につき、移転しました。情報が古い可能性があるので、ご注意ください。

やること

第1回でご紹介した通り、Zendeskはブラウザから使えますが、Zendesk APIを利用すると、Webサイトと連携することができます。
今回は、Ruby on Railsを使って、Zendesk APIにアクセスし、Zendeskのチケットを表示してみます。

今回使うgem

Rails(Ruby)からZendesk APIにアクセスするために、Zendeskから"zendesk_api"gemが提供されています。

READMEに設定方法が書かれているので、ざっくりご覧ください。

Ruby on Railsで実装してみよう

準備

rails new zendesk_api_with_rails
cd zendesk_api_with_rails

Zendesk APIのgemを追加

Gemfile に↓を追加して、

gem 'zendesk_api'

インストールします。

bundle install

Zendesk APIにアクセスに必要な情報を集める

APIアクセスには、ユーザ名/パスワードかユーザ名/APIトークンのいずれかを使います。
今回は、ユーザ名/APIトークンでアクセスしてみます。

Zendeskにログインして、
「管理」ー「チャネル」ー「API」をクリックし、
「トークンアクセス」を有効にして、APIトークンします。
すぐ下にcurlコマンドが表示されているので、「YOUR_TOKEN」の部分を自分用のAPIトークンに入れ替えて、ターミナルで実行してみてください。

curl -u xxx@example.com/token:YOUR_TOKEN https://xxx.zendesk.com/api/v2/users/me.json

Zendesk APIクライアント用ファイルを追加

Zendesk APIクライアントを取得するため、config/initializersに、zendesk_api_init.rbを作成します。

いろいろ書いてありますが、設定するのはENV['...']がある3箇所だけです。

class ZendeskApiInit
  def self.client
    @client ||= ZendeskAPI::Client.new do |config|
      # Mandatory:

      config.url = ENV['ZENDESK_URL'] # e.g. https://mydesk.zendesk.com/api/v2

      # Basic / Token Authentication
      config.username = ENV['ZENDESK_USERNAME']

      # Choose one of the following depending on your authentication choice
      config.token = ENV['ZENDESK_TOKEN']
      # config.password = "your zendesk password"

      # OAuth Authentication
      # config.access_token = "your OAuth access token"

      # Optional:

      # Retry uses middleware to notify the user
      # when hitting the rate limit, sleep automatically,
      # then retry the request.
      config.retry = true

      # Logger prints to STDERR by default, to e.g. print to stdout:
      require 'logger'
      config.logger = Logger.new(STDOUT)

      # Changes Faraday adapter
      # config.adapter = :patron

      # Merged with the default client options hash
      # config.client_options = { :ssl => false }

      # When getting the error 'hostname does not match the server certificate'
      # use the API at https://yoursubdomain.zendesk.com/api/v2
    end
  end
end

環境変数を設定

zendesk_api_init.rbで使用する環境変数を設定します。環境変数はENV['xxx']を使って、アクセスできます。

# Zendesk
export ZENDESK_USERNAME=xxx
export ZENDESK_TOKEN=xxx
export ZENDESK_URL=https://xxx.zendesk.com/api/v2

.bash_profile 辺りに上記の環境変数を設定しておくと便利です。

設定後、

source ~/.bash_profile

コマンドを実行して、追加した環境変数を有効にするのをお忘れなく。

Zendesk APIクライアントの動作確認

rails console
> client = ZendeskApiInit.client # クライアントを作成
> client.tickets.first # 最初に作成したチケットを取得する

ブラウザからチケットを表示

ブラウザからチケットを表示するために、コントローラとビューを追加します。

コントローラとビューを追加

コントローラzendesk_tickets_controller.rbを作成し、indexメソッドを追加します。

class ZendeskTicketsController < ApplicationController
  def index
    @tickets = ZendeskApiInit.client.tickets.page(1).per_page(10) # 10チケットを取得して、最初の1ページ目を表示。pageメソッドが表示されるページで、per_pageメソッドがページに表示するデータ数。
  end
end

apps/viewsにzendesk_ticketsディレクトリを作成し、index.html.erbを作成します。

<h1>ZendeskTickets#index</h1>

<table>
  <thead>
    <tr>
      <th>Id</th>
      <th>Subject</th>
      <th>Description</th>
      <th>Created at</th>
    </tr>
  </thead>

  <tbody>
    <% @tickets.each do |ticket| %>
      <tr>
        <td><%= ticket.id %></td>
        <td><%= ticket.subject %></td>
        <td><%= ticket.description %></td>
        <td><%= ticket.created_at %></td>
      </tr>
    <% end %>
  </tbody>
</table>

ルーティングの設定

config/routes.rb にルーティング設定をします。

get "zendesk_tickets/index"

チケット一覧を確認

http://localhost:3000/zendesk_tickets/indexにアクセスしてみましょう！

＊scaffold.css.scssをコピーしてくると、見た目がややマシになります（笑

個別チケット確認のために、コントローラとビューを更新・追加

コントローラzendesk_tickets_controller.rbを作成し、showメソッドを追加します。

def show
  @ticket = ZendeskApiInit.client.tickets.find(id: params[:id])
end

個別チケットページに遷移しやすいように、indexページのSubjectにリンクを設置します。

<% @tickets.each do |ticket| %>
  <tr>
    <td><%= ticket.id %></td>
    <td><%= link_to ticket.subject, "/zendesk_tickets/#{ticket.id}" %></td>
    <td><%= ticket.description %></td>
    <td><%= ticket.created_at %></td>
  </tr>
<% end %>

ルーティングの設定

config/routes.rb に showメソッドへのルーティングを設定します。

get "zendesk_tickets/:id" => "zendesk_tickets#show"

チケット作成の確認

http://localhost:3000/zendesk_tickets/indexにアクセスして、Subjectをクリックしてみましょう！

＊チケットが存在していなければ、もちろん、表示されません。
その場合は、チケットを作成してから試してみてください。

まとめ

うまく動いたでしょうか？

本当は、チケットの作成までやるつもりでしたが、結構長くなってきたので、一旦終わりにします。
あとは、zendesk_api gemのREADMEを参考にやってみてください。

Zendesk APIによって、Zendeskで蓄積した電話やメールなどの顧客対応履歴を、Webサイトの動きに反映できます。また逆方向に、Webサイトでの顧客の行動（サポート依頼、苦情、資料請求など）を、Zendeskのチケットとして蓄積することもできます。

クラウド以前は、こういうことをするのはなかなか大変なことでしたが、今ではZendesk APIを叩けば、チケットデータを出し入れできます。本当にすごい時代になったものです。

どのように活用して、お客さんに価値を提供できるか、考えてみてはいかがでしょうか。

サンプルコードのダウンロード

上記のサンプルコードは、Githubよりダウンロードできます。

https://github.com/fuji3zpg/zendesk_api_show_tickets

参考情報

Railsの実装周りは、"zendesk_api"gemのREADME・Wiki・テストコードが参考になります。
Zendesk APIの公式記事は、Zendesk APIに関する概説があります。
ググってみたら、"zendesk_api_client_rb"gemに関する情報は↓のZendesk公式API以外にはほぼない感じでした。なので、英語ですが、まずはこのページをじっくり読むのがいいと思います。

http://developer.zendesk.com/documentation/rest_api/introduction.html