API を使って Jira ServiceDesk にリクエストを作成

はじめに

表題の通り、API 経由で Jira ServiceDesk にリクエストを作成しました。

OAuth2.0 でトークン取得せよとか、OAuth1.0でトークン取得せよとか、APIトークン取得せよとか、ID/パスワードで Basic認証せよとか、APIのバージョンによって違う点もあって少々混乱したこともあり、備忘メモです。

参考にした ServiceDesk の APIドキュメント はこちらです。

1. アプリを登録する

まずは、APIを利用するアプリを登録します。
詳細は Manage your apps を参照。

1.1. My apps でアプリを作成する

• Attlasian Developer My apps にアクセス

• [Create] > [OAuth 2.0 Integration] を押下
  

• Name を入力して [Create] を押下
  

• 作成完了
  

1.2. 作成したアプリで利用する scope を設定する

• [Permissions] のメニューを開く

• 利用するAPI に対して [Add] を押下する （押下すると [Configure] の名前になる）
  

• 利用するAPI の [Configure] を押下して詳細画面を開く

• 詳細項目で、利用するスコープに対して [Add] を押下する（押下すると [Remove] の名前になる）
  

1.3. 作成したアプリの redirect_uri を設定する

• [Authorization]のメニューを開く

• OAuth 2.0 の項目の [Configure] を押下する
  

• [Callback URL] の項目に、redirect_uri として使うURLを記入する

• [Sace Changes] を押下する
  

• [Callback URL] を登録したら表示される [Authorization URL generator]で generateされている Authorization URL は認可コードを取得する時に使います！

2. cloudId を確認する

利用するAPIのエンドポイントを確認すると、下記の通り記載されてます。（参考：Structure of the REST URIs）

http://host:port/context/rest/servicedeskapi/XXXXXX

host と context が自分の環境の場合何になるのかわかりませんでしたが、この辺とか見て、下記が怪しいなと思って試したら使えたのできっとこれ。

https://api.atlassian.com/ex/jira/<cloudId>/rest/XXXXX

ってことで cloudId とやらを取得します。
Get the cloudid for your site を参考に取得します。

2.1. cloudId を確認する APIを叩くための token を取得する

cloudId を確認する APIはこれです。

https://api.atlassian.com/oauth/token/accessible-resources

このAPIを叩くための token を、1. アプリを登録する で登録した情報を使って取得します。

2.1.1. 認可リクエスト

• 1. アプリを登録する で [Callback URL] を登録した後、[Authorization URL generator] で Authorization URL が generate されているので、それを使います。
• そのままコピーすると、state の値が {YOUR_USER_BOUND_VALUE} となっているので、適宜修正して使います。
• scope の値も、アプリの登録時にアプリが利用するscopeとして設定したものが全て記されているので、こちらも適宜必要なもののみに修正して使います。
  
• 同意画面が表示されるので、問題ないことを確認して同意します。
• 認可コードが [Callback URL] に登録したURLに返却されます。

2.1.2. アクセストークン取得

• 取得した認可コードを使ってアクセストークンを取得します
• 詳細は Exchange authorization code for access token を参照

トークンエンドポイント

https://auth.atlassian.com/oauth/token

• 必要なパラメータは下記
  • client_id: (required)
  • client_secret: (required)
  • code: (required)
  • redirect_uri: (required)
• 通常パラメータは Content-Type application/x-www-form-urlencoded で送付するのが仕様ですが application/json で送る必要がある点、要注意です。

2.2. cloudId を取得する

「2. cloudId を確認する」で記した通り、Get the cloudid for your site を参考に取得します。

3. APIトークンの取得

APIのエンドポイントもこれでわかったし、アクセストークンの取得の手順も完璧。

ですが、私が使いたかった、冒頭にドキュメントのURLを記したAPI達は APIトークン を使ってアクセスするもののようです。
Manage API tokens for your Atlassian account を参考にAPIトークンを取得します。

API トークン のページ にアクセスして [APIトークンを作成する] を押下するだけです！

4. APIを利用してリクエストを作成

これでようやくAPIを利用するための準備が整いました。長かった。

4.1. serviceDeskId と requestTypeId を確認する

とはいえ APIの利用には、どの ServiceDesk にリクエストを作成するのかを指定する serviceDeskId と、その中のどの種類のリクエストを作成するかを指定する requestTypeId が必要です。

ServiceDeskのポータルのカスタマーがリクエストを送信する画面、URLのパス上の下記の位置にそれぞれある数字が serviceDeskId と requestTypeId です。

リクエスト画面のURL

https://xxxx.atlassian.net/servicedesk/customer/portal/{serviceDeskId}/group/1/create/{requestTypeId}

例えば

• https://samiii.atlassian.net/servicedesk/customer/portal/1/group/8/create/111

の場合は、 serviceDeskId が 1、requestTypeId が 111 です。

4.2. 対象のリクエストタイプに存在する各項目のパラメータ名を確認する

リクエストを作成する際に、各項目のパラメータ名を確認する必要があります。 ServiceDeskの画面から確認できるフィールド名とは別にそれぞれ指定する id となる文字列が存在するので、それを取得します。

Get request type fields のAPIを使って取得してください。

この API は、APIトークンを使って叩くので、ヘッダに下記のように APIトークンを使ったBasic認証を付して利用します。

Authorization: Basic {"メールアドレス:APIトークン"をbase64エンコードした文字列}  

4.3. リクエストを作成する

以上で必要な情報が全て揃いました。

リクエストの作成は Create Customer Request のAPIを使って行います。詳細はAPIドキュメントを確認ください。

この API は、「4.2.」 で使ったAPIと同様にAPIトークンを使って叩くので、ヘッダに下記のように APIトークンを使ったBasic認証を付して利用します。

Authorization: Basic {"メールアドレス:APIトークン"をbase64エンコードした文字列}  

---

以上でAPI経由でリクエストが作成できました！

ちなみに、「自動化」の Webhook を使って、リクエスト作成の処理を書いて、Webhook の URL に JSONでパラメータ送りつけてもできます。そっちの方が簡単です。

ただ、APIでリクエスト作成したら、作成に成功したか否かとか、どのURL（課題番号）で作成されたかとか、普通必要ですよね？ Webhook はその名の通りなので、特に結果を返却してはくれません。

ただ、結果の返却不要で、ある程度適当で良いよ、であれば「自動化」のWebhook使った方が断然早いですのでそちらも試してみるといいと思います。

おしまい。