2024年12月16日
Jira Cloud で GraphQL API を使ってみた樋口 晃 Akira Higuchi
こんにちは、リックソフトでカスタマーサポートをしている樋口です。私が所属しているチームは、日々お客様からのお問い合わせに答えています。
お客様からのお問い合わせは、もちろんITIL4に準拠したリクエスト管理ツール「Jira Service Management (JSM)」で受け付けています。
リックソフトのお問い合わせ受け付け Jira は、開設して 15年が経過しました。開設当時の Jira, Confluence は今でいうサーバー版しか無かったので、サーバー版の質問に対応していました。今では サーバー版は無くなり、Data Center 版の質問 と Atlassian Cloud の質問に対応しています。
参考▶リックソフトはアトラシアン製品の有償サポートプログラム「サポートプラス」を提供しています
Cloud になってから、API に関する質問が少しずつですが増えました。これは、Cloud になって Atlassian 製品を他の製品と Integration(連携) する機会が増えたからだと思います。Jira Cloud での API と言えば、下記の REST API が使われる事が多いと思います。
▶参考記事:【クラウド版でも!】JiraのREST API を使ってみよう―リックソフトブログー
REST API も良いのですが、最近では GraphQL という API が出てきました。REST API に無い便利さもあり、浸透してきていると思います。
このブログでは、GatphQL の Jira Cloud での利用についてご紹介します。
本ブログでは、Jira Cloud しか扱っていませんが、Atlasian の GrapthQL は Confluence, Bitbucket, Trello もサポートしています。
<もくじ>
GrapthQL というのはどんなものか、リックソフト社内の生成AI、AIrick(あいりっく)に質問してみました。
▶AIrickについて:生成AI活用で業務改善を図る<リックソフトのユースケース>-リックソフトブログー
GraphQLは、Facebookによって開発されたクエリ言語であり、APIのデータ取得方法を定義するためのランタイムです。以下にGraphQLの主な特徴を挙げます。
GraphQLの特徴
(A):柔軟なデータ取得 :クライアントは必要なデータだけを指定して取得できるため、過剰なデータ転送を避けることができます。
(B):型システム: スキーマを使用してデータの型を定義し、クエリの構造を明確にします。
(C):単一エンドポイント: すべてのデータ要求は単一のエンドポイントを通じて行われます。
(D):クライアント主導のデータ取得:クライアントは必要なデータの構造を指定し、その構造に従ってサーバーからデータを取得します。これにより、必要なデータだけを効率的に取得できます。
GraphQLの使用例
1. クエリの作成: 必要なフィールドを指定してデータを取得します。
2. ミューテーション: データの作成、更新、削除を行います。
3. サブスクリプション: データの変更をリアルタイムで受け取ります。GraphQLは、特にフロントエンド開発者にとって、効率的にデータを取得し、アプリケーションのパフォーマンスを向上させるための強力なツールです。
との事でした。
私はこの中で、(C) 単一エンドポイントと (D)クライアント主導のデータ取得が REST API と比べて魅力的だと思っています。
「単一のエンドポイント」:REST API の場合は、欲しい情報によりエンドポイント(アクセスするURL)が違います。これに対して、GraphQL はエンドポイントは一つです。一つのエンドポイントに色々なリクエストを送信する事で欲しい情報を指定します。
「クライアント主導のデータ取得」:REST API の場合、API の仕様で決められたデータが全て送信されます。一部、パラメータで指定できる例外もありますが、基本は決められた項目すべてです。これに対して、GraphQLの場合は、クライアントが指定したデータだけが送信されます。Jira の課題の情報を REST API で取得すると、カスタムフィールドも含めてかなり多くのフィールドを含んた JSON がサーバーから送信されるので、欲しいデータを探さなければいけないのですが、GraphQLの場合は必要なフィールドをリクエストする事ができて便利です。
GrapthQLの詳細は https://graphql.org/ などをご参照下さい。自分が勉強したときは、動画「HowToGraphQL (Fundamentals) - Core Concepts (3/4)」が理解に役立ちました。
早速、試してみましょう。あなたが Jira Cloud のユーザーなら、すぐに試せます。
今使っている、Jira Cloud の URL に /gateway/api/graphql を追加してアクセスしてみて下さい。
例えば、Jira Cloud の URL が 「https://rickma-graphql.atlassian.net/」 なら、 「https://rickma-graphql.atlassian.net/gateway/api/graphql」 にアクセスして下さい。下記の様な画面が見れる筈です。この画面が表示されたら、もう準備は完了です。
左側のペインにリクエストを入れるて、赤い実行ボタンを押すと右側に結果が表示されます。
REST API の時は、ドキュメントを確認してエンドポイントやパラメータを確認してリクエストを作っていました。
Atlassian のドキュメント「GraphQL API」を読んでも、Jira の情報が有りません。
でも、大丈夫です。GraphQL Gateway のオンラインドキュメントで確認できます。
GrapthQL を利用するには、お使いの Atlassaian Cloud の cloudId が必要なので、以下の Query「your-domain」をお使いの ドメインに変更して、下記 を実行して cloudId を取得して下さい。
query example {
tenantContexts(hostNames:["your-domain.atlassian.net"]) {
cloudId
}
}
下記の様な結果が取得できる筈です。
"data": {
"tenantContexts": [
{
"cloudId": "1234567c-1234-1234-b1b2-b123456789f"
}
]
},
"extensions": {
"gateway": {
"request_id": "1a91e4938faa4c22ac61b266d348fbf0",
"crossRegion": false,
"edgeCrossRegion": false
}
}
}
上記の 1234567c-1234-1234-b1b2-b123456789f が CloudId ですので、記録しておいて下さい。
オンラインヘルプの項目から、Jira を選択してその中から issuesearch を選んで下さい。 下記の様に表示されます。
issueSearch の下に赤い波線が出ているのはエラーが有るという事です。何のエラーかというと、フィールドの指定がないのです。3行目の最後に "{}" を追加して過去の中にカーソルが有る状態で Ctrl + Space を押してみて下さい、下記の様な表示になり候補が表示されます。
この中から totalcaount を選択すると、コードは下記の様になり、取りえずエラーは無くなります。
ちょっと見にくいので、下記の赤丸で囲った 「整形ボタン」で成形します。
整形すると下記の様になります。
同じ要領で、コードを追加して下記の様にします。下記は課題のフィールドとして、課題キーと要約を指定しています。また検索条件として、jql も指定しています。
これを実行するとエラーになってしまいます。
エラーメッセージを読むと、issueSearch に @optIn(to:"JiraSpreadsheetComponent-M1") が必要と記載されています。メッセージに従って追加すると、下記の様に成功します。
上記の様に、REST API に比べて指定したフィールドだけが表示されるというところが、私は便利だと思っています。Ctrl + Space でコードでフィールドが追加できますので、追加してみて下さい。また、 issueSearch 以外にも色々な機能が有りますので、やってみると面白いです。オンラインドキュメントとコードアシストを利用して、色々な情報を取得する事も、REST API よりも便利だと思いました。
上記は OptIn が必要な例ですが、HTTP ヘッダーに情報が必要なケースも有ります。
You MUST provide a 'X-ExperimentalApi : JiraIssueDevInfoDetails' HTTP header to use the field 'devInfoDetails'
とエラーメッセージに 記載されています。この場合は、下記の様に画面下の「Headers」を開いて、パラメータを追加すると成功します。
簡単に GrapthQL Gateway について紹介させて頂きました。色々な製品の Integration をする場合、製品ごとに API マニュアルを読んでを調べるのは大変でしたが、GraphQL が浸透すれば、REST API よりも少ない工数で API を利用する事が出来ると期待しています。
できれば、Python コード や Workato から GraphQL を利用する例もご紹介したかったのですが、今回は割愛させて頂きました。また機会があれば、ご紹介したいと思います。
「Jiraを組織全体で定着させたい」という方へ。リックソフトでは、ユーザー向け無料のセミナー(不定期開催)や研修サービス(有償)を提供しています。ぜひご利用ください。
Jira 入門コース e-ラーニング Jira 入門コースリックソフトは、アトラシアン製品を「製品の魅力を十分に引き出して使いたい」という企業の伴走型サポートを行っています。導入実績132社(2024年4月現在)。
リックソフトのサポートプラス本情報はブログを公開した時点の情報となります。
ご不明な点はお問い合わせください。
アトラシアン社ではサポート範囲外となっているサードパーティ製のアドオンをリックソフトのサポートではサポートします。
リックソフトのサポートは開発元が提供するサポート以上の価値があります。
ツールを導入しただけでは成功とはいえません。利用者が効果を感じていただくことが大切です。独自で制作した各種ガイドブックはツール活用を促進します。
リックソフトからライセンス購入を頂いたお客様にはガイドブックを無料進呈いたします。
ツール操作の研修だけでなく「ウォータフォール型開発」「アジャイル型開発」のシミュレーション研修も提供。
日本随一の生産性向上にも効果のある研修サービスです。
リックソフトからライセンス購入を頂いたお客様には無料招待や割引特典がございます。