HCP Terraform API の利用方法

HCP Terraform では、公式 API ドキュメントに沿って API コールを行うことで、様々な操作が可能です。

認証用トークンの準備

公式ドキュメントに記載されているように、API 認証には Bearer トークンが必要です。

トークンの種類と選択

トークンには複数の種類があり、利用する API によって適切なトークンを選択する必要があります。

例えば、Retrieve the JSON execution plan API の場合、下記のように記載されています。

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token that has admin level access to the workspace. (More about permissions.)

この場合、Organization token は使用できず、適切な権限を持つ User token または Team token が必要です。

重要な注意点

• 使用するトークンの種類を確認
• 対象ユーザーやチームに適切な権限が付与されていることを確認

API 呼び出し方法

API の呼び出しは、ドキュメントに記載されている curl サンプルに従って実行できます。

ドキュメントの前提条件

記載されているサンプルは、下記の前提になっているようです。

• 環境変数 TOKEN にトークン値が設定されている
• payload.json ファイルにリクエストペイロードが保存されている

各 API のドキュメントにはレスポンスコードに関する記述も含まれているため、適切なエラーハンドリングの実装が可能です。

具体的な実装例：アカウント情報の更新

ここでは、Update your account info API を使用してユーザー名を変更する手順を説明します。

(1) User token の生成

1. HCP Terraform の Tokens のページにアクセス
2. Create an API token をクリックし、以下の項目を設定
   • Description: トークンの説明
   • Expiration: 有効期限を設定
3. Generate token をクリック

完了すると、下記の赤枠内に生成されたトークンが表示されます。
他のページに遷移したりブラウザを閉じたりすると消えてしまうため、すぐに安全な場所にメモしておきます。

(2) リクエストペイロードの作成

payload.json

{
  "data": {
    "type": "users",
    "attributes": {
      "email": "<アカウントのメールアドレス>",
      "username": "<新しいユーザー名>"
    }
  }
}

(3) API の実行

User token を環境変数 TOKEN に設定し、curl を実行します。
(payload.json が存在するディレクトリで実行する想定)

# トークンを環境変数に設定
TOKEN="<作成したトークン>"

# APIリクエストの実行
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/account/update

(4) 結果の確認

変更が成功したら、Profile ページでユーザー名が更新されていることを確認できます。

ユーザー名に使用できない文字が含まれている場合、以下のようなエラーレスポンスが返されます：

{
  "errors": [
    {
      "status": "422",
      "title": "invalid attribute",
      "detail": "Username can include only letters, numbers, and dashes",
      "source": { "pointer": "/data/attributes/username" }
    }
  ]
}