VS CodeからREST APIを実行してConfluenceライセンスを付与する

:::note info
この記事は 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 は使えるようです。

<https://community.atlassian.com/t5/Confluence-questions/Free-%E3%83%97%E3%83%A9%E3%83%B3%E3%81%A7-API-%E3%81%AF%E4%BD%BF%E7%94%A8%E3%81%A7%E3%81%8D%E3%81%BE%E3%81%99%E3%81%8B/qaq-p/1636694>

# VS Code から REST API を実行する

VS Code に「REST Client」をインストールすることで、VS Code から REST API を実行できるようになります。

## REST Client のインストール

REST Client を VS Code にインストールする方法は以下の通りです。

1. VS Codeを起動して `拡張機能` アイコンをクリックします。
1. 検索バーに「REST Client」と入力します。
1. 一番上に「REST Client」が表示されますので、これをインストールします。

![REST Client.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/ea57d8d8-7e79-05b3-a5e8-99bf96c011eb.png "REST Clientのインストール")

## REST Client の使い方

__POST__ する場合の基本的な使い方です。

```http:POST
POST https://example.com/comments HTTP/1.1
content-type: application/json

{
    "name": "sample",
    "time": "Wed, 21 Oct 2015 18:27:50 GMT"
}
```
1. VS Codeを開き、上記の形式でリクエストを入力します。リクエストヘッダから1行空けてリクエストボディを書きます。
1. 以下のいずれかの方法でリクエストを送信します。
    - Windows の場合 `Ctrl + Alt + R`
    - Mac の場合 `command + option + R`
    - VS Code メニューの `表示` → `コマンド パレット` → `Send Request` ![Send Request.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/74470de8-2c27-a0b6-9dee-f62367bf8219.png "VS Code のコマンド パレットから Send Request を実行")
1. レスポンスが VS Code の画面右側に表示されます。 ![Response.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/5822ba13-88f9-dc5b-bbb0-f98b4e8a935a.png "送信したリクエストのレスポンス")

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)] にアクセスし、作成します。

<https://id.atlassian.com/manage-profile/security/api-tokens>

![APIトークンの作成.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/a6a60c41-d6bf-a612-7c13-3379f7f4df47.png "API トークンの作成と管理")

![APIトークンの作成2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/85403655-6f61-508f-0752-5eaca37dd8d2.png "API トークンを作成する")

Atlassian Support による公式ドキュメントもありますので、こちらもご参照ください。

<https://support.atlassian.com/ja/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/>

### 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 エンコードします。

```zsh:Linux/Unix/MacOS
echo -n hogehoge@example.com:your-api-token | base64
```

```powershell:Windows10
$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されます。

![管理画面.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/b13517f9-0213-2b5f-9b90-340a342d8e8d.png "ユーザー管理画面")

以上から、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` を指定します。

```:Confluence-Cloud-REST-API
https://your-domain.atlassian.net/wiki/rest/api/group/user?name={name}
```

https://developer.atlassian.com/cloud/confluence/rest/api-group-group/#api-wiki-rest-api-group-user-post

Jira Cloud も利用している場合は Jira Cloud REST API を利用してグループにユーザー追加することもできます。
こちらも `your-domain` に自分の利用しているインスタンス名、`{groupname}` に `confluence-users` を指定します。

```:Jira-Cloud-REST-API
https://your-domain.atlassian.net/rest/api/3/group/user?groupname={groupname}
```

POST する際に、グループに追加する Atlassian アカウントの `accountId` を指定します。

```json:JSON
{
    "accountId": "<string>"
}
```

`accountId` は Web のユーザー管理画面や各ユーザーのプロファイルページのURLから確認できます。

![AccountId.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/41a5fe83-4025-d1f3-6e2d-f6d841bb3c8d.png "プロファイルの URL から accountId を確認する")

### グループにユーザーを追加

実際に REST API を実行して `confluence-users` グループに追加します。

```http:Confluence-Cloud-REST-API
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>"
}
```

```http:Jira-Cloud-REST-API
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](https://support.atlassian.com/ja/cloud-automation/docs/jira-cloud-automation/) と [Smart Values](https://support.atlassian.com/ja/cloud-automation/docs/smart-values-in-jira-automation/) を利用して自動化できます。
Automation for Jira では　Web リクエストを送信することができ、その際に Smart Values でユーザーの `accountId` を指定できます。

機会があれば、この自動化設定についても書いてみたいと思います。

![自動化の設定画面.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/234372/f047f47a-8ac4-8dc3-ac7c-8cfa9fa69572.png "自動化の設定画面")

# 最後に

Atlassian のクラウド製品は Free プランもあるので、業務で使っていないという方でも自分用にインスタンスを作成して利用することが可能です。
ご興味のある方は試してみては如何でしょうか？

<https://www.atlassian.com/ja/software/free>