この記事は MicroAd Advent Calendar 2021 の 10 日目の記事です。
https://qiita.com/advent-calendar/2021/microad
概要
こんにちは、コーポレートエンジニアの まいまい です。
この記事では VS Code の Extension (拡張機能) である「REST Client」を使って REST API を実行し、指定した Atlassian アカウントに Confluence ライセンスを付与する方法を紹介します。
目的
いろいろなサービスで提供されている Web API を使った開発では、事前に API を実行して動作検証をすると思います。
私の場合、Chrome のアプリや Postman などを利用していましたが、VS Code を使って作業をしているので、「VS Code から API を実行できるなら実行したい」と思っていました。
また、私は業務で Atlassian 製品の管理や構成、API を使った開発をしているので、REST API の利用方法を紹介したいと思っていました。
以上から、今回の記事の目的は
- VS Code から REST API を実行する
- REST API を実行して指定した Atlassian アカウントに Confluence ライセンスを付与する
の2つについて紹介することになります。
前提
今回は Confluence Cloud Standard プラン を利用しています。
また、Confluenceライセンスを付与するため、 サイト管理者の権限を持った Atlassian アカウント で API トークンを発行し、REST API を実行しています。
ちなみに、Free プランでも REST API は使えるようです。
VS Code から REST API を実行する
VS Code に「REST Client」をインストールすることで、VS Code から REST API を実行できるようになります。
REST Client のインストール
REST Client を VS Code にインストールする方法は以下の通りです。
- VS Codeを起動して
拡張機能アイコンをクリックします。 - 検索バーに「REST Client」と入力します。
- 一番上に「REST Client」が表示されますので、これをインストールします。
REST Client の使い方
POST する場合の基本的な使い方です。
POST https://example.com/comments HTTP/1.1
content-type: application/json
{
"name": "sample",
"time": "Wed, 21 Oct 2015 18:27:50 GMT"
}
- VS Codeを開き、上記の形式でリクエストを入力します。リクエストヘッダから1行空けてリクエストボディを書きます。
- 以下のいずれかの方法でリクエストを送信します。
- Windows の場合
Ctrl + Alt + R - Mac の場合
command + option + R - VS Code メニューの
表示→コマンド パレット→Send Request
- Windows の場合
- レスポンスが VS Code の画面右側に表示されます。
REST Client の操作方法についてはこちらの記事で詳しく紹介されていますので、ご興味のある方はご参照ください。
https://qiita.com/toshi0607/items/c4440d3fbfa72eac840c
REST API を実行して指定した Atlassian アカウントに Confluence ライセンスを付与する
続きまして、REST API を実行して指定した Atlassian アカウントに Confluence ライセンスを付与する方法を紹介します。
APIトークンの準備と認証
Atlassian 製品の REST API を利用するには API トークン が必要になります。
API トークンを作成するには、自分の Atlassian アカウント管理ページの [セキュリティ] → [API トークン] → [API トークンの作成と管理] にアクセスし、作成します。
https://id.atlassian.com/manage-profile/security/api-tokens
Atlassian Support による公式ドキュメントもありますので、こちらもご参照ください。
Basic 認証方法
REST Client から Jira Cloud REST API を実行する場合、作成した API トークン your-api-token を以下のように指定して Basic 認証します。
Authorization: Basic hogehoge@example.com:your-api-token
補足：Google Apps Script や Python などで利用する場合
GAS や Python など、コードから Jira Cloud REST API を実行する場合、先ほどの hogehoge@example.com:your-api-token を直接指定するのではなく、BASE64 エンコードされた文字列を指定して Basic 認証します。
(1) hogehoge@example.com:your-api-token を BASE64 エンコードします。
echo -n hogehoge@example.com:your-api-token | base64
$Text = 'hogehoge@example.com:your-api-token'
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)
$EncodedText = [Convert]::ToBase64String($Bytes)
$EncodedText
(2) 出力された文字列 (例:dXNlcmVtYWlsOmFwaV90b2tlbg==) をヘッダに指定し、Basic 認証します。
※REST Client でもこの形式で指定できます。
Authorization: Basic dXNlcmVtYWlsOmFwaV90b2tlbg==
今回紹介した内容も含め、Atlassian の開発者向けサイトに Basic 認証についてのドキュメントが公開されていますので、こちらもご参照ください。
https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/
REST APIの実行
Confluence のライセンスを付与するには
Web の管理画面でライセンス付与/削除する場合、そのユーザーのアカウント画面を開き、対象の製品のアクセスを ON/OFF しますが、ここの ON/OFF に連動してその製品用の Atlassian グループ (例:confluence-users) にユーザー追加/削除されています。
また、製品用の Atlassian グループにユーザー追加/削除すると、追加/削除したユーザーの製品アクセスもON/OFFされます。
以上から、REST API を実行し、指定した Atlassian アカウントを Atlassian グループ confluence-users にユーザー追加すると、Confluence のライセンスを付与することができます。
ちなみに、Jira Software 用のグループは jira-software-users、Jira Service Management 用のグループは jira-servicedesk-users になります。
使用する REST API
Confluence Cloud REST API を利用する場合、以下を利用します。
your-domain に自分の利用しているインスタンス名、{name} に confluence-users を指定します。
https://your-domain.atlassian.net/wiki/rest/api/group/user?name={name}
Jira Cloud も利用している場合は Jira Cloud REST API を利用してグループにユーザー追加することもできます。
こちらも your-domain に自分の利用しているインスタンス名、{groupname} に confluence-users を指定します。
https://your-domain.atlassian.net/rest/api/3/group/user?groupname={groupname}
POST する際に、グループに追加する Atlassian アカウントの accountId を指定します。
{
"accountId": "<string>"
}
accountId は Web のユーザー管理画面や各ユーザーのプロファイルページのURLから確認できます。
グループにユーザーを追加
実際に REST API を実行して confluence-users グループに追加します。
POST https://your-domain.atlassian.net/wiki/rest/api/group/user?name=confluence-users HTTP/1.1
Authorization: Basic hogehoge@example.com:your-api-token
Accept: application/json
Content-Type: application/json
{
"accountId": "<string>"
}
POST https://your-domain.atlassian.net/rest/api/3/group/user?groupname=confluence-users HTTP/1.1
Authorization: Basic hogehoge@example.com:your-api-token
Accept: application/json
Content-Type: application/json
{
"accountId": "<string>"
}
応用事例
今回は REST Client から REST API を実行しましたが、
この内容を応用して、例えば Jira Service Management で Atlassian アカウントの申請を管理している場合、ライセンスの付与/削除を Automation for Jira と Smart Values を利用して自動化できます。
Automation for Jira では Web リクエストを送信することができ、その際に Smart Values でユーザーの accountId を指定できます。
機会があれば、この自動化設定についても書いてみたいと思います。
最後に
Atlassian のクラウド製品は Free プランもあるので、業務で使っていないという方でも自分用にインスタンスを作成して利用することが可能です。
ご興味のある方は試してみては如何でしょうか？