Zenn
📝

[AWS][API Gateway] デプロイの説明文を変更する

2024/12/12に公開
AWS
Amazon API Gateway
AWS CLI
tech

AWS API Gatewayの、作成済みデプロイの説明文ですが、2024年12月12日現在、マネジメントコンソールからは変更ができません。

デプロイの説明文を変更したい場合は、現状、AWS CLIもしくはAWS SDKを使う必要があります。

この記事では、AWS CLIを使った方法を説明します。

AWS CLIでデプロイの説明文を変更する

aws apigateway update-deploymentコマンドで、次のように修正します：

aws apigateway update-deployment \
  --rest-api-id <APIのID> \
  --deployment-id <デプロイID> \
  --patch-operations op=replace,path=/description,value="<修正後のデプロイ説明文>"

デプロイの説明文が、やや長めになる場合や、[などのややこしい文字を含む場合は、JSONファイルを使った方法がよいでしょう。
aws apigateway update-deploymentコマンドの各オプションを指定したJSONファイルを用意して、それをaws apigateway update-deploymentコマンドの--cli-input-jsonオプションで指定して実行します：

  1. まず、aws apigateway update-deploymentコマンドを--generate-cli-skeletonオプションつきで実行し、出力をリダイレクトして雛形JSONファイルを作成します：

    雛形JSONファイル作成例（ファイル名は自由です）
    aws apigateway update-deployment --generate-cli-skeleton \
  > ./update_deployment_foobar_description.json
    コマンド「aws apigateway update-deployment --generate-cli-skeleton」の出力
    aws apigateway update-deployment --generate-cli-skeleton
    出力
    {
    "restApiId": "",
    "deploymentId": "",
    "patchOperations": [
        {
            "op": "add",
            "path": "",
            "value": "",
            "from": ""
        }
    ]
}

  2. 1で作成した雛形JSONファイルを編集します：

    ./update_deployment_foobar_description.json（ファイル名は自由です）
    {
    "restApiId": "<APIのID>",
    "deploymentId": "<デプロイID>",
    "patchOperations": [
        {
            "op": "replace",
            "path": "/description",
            "value": "[v1.0] 〇〇機能を実装"
        }
    ]
}

  3. 2で作成したJSONファイルを--cli-input-jsonオプションで指定し、aws apigateway update-deploymentコマンドを実行します：

    コマンド例（JSONファイル名は自由です）
    aws apigateway update-deployment \
  --cli-input-json file://./update_deployment_foobar_description.json

【補足】デプロイ情報の確認方法

AWS CLIで確認する

特定のデプロイの情報を確認する場合は、aws apigateway get-deploymentコマンドを使います：

aws apigateway get-deployment \
  --rest-api-id <APIのID> \
  --deployment-id <デプロイID>

デプロイ情報の一覧を確認する場合は、aws apigateway get-deploymentsコマンドを使います：

aws apigateway get-deployments \
  --rest-api-id <APIのID>

マネジメントコンソールから確認する

  1. API Gatewayのマネジメントコンソール左ペインの「API」からAPI一覧を開き、APIを選択します：

  2. 左ペインから「ステージ」を選択します：

  3. ステージ画面の下部、「デプロイ履歴」タブをクリックすると、デプロイの一覧を見ることができます。

【補足】デプロイとステージの関係

マネジメントコンソールでAPI Gatewayに触れていると、デプロイの一覧を直接確認する画面が存在せず、ステージの画面から間接的にデプロイの一覧を見るしかないので、デプロイとステージの関係がややわかりづらいです（2024年12月12日現在）。ここで補足しておきます。

結論から言うと、「まず一本のデプロイのストリームが存在し、各ステージはその中のどこかの一つのデプロイを指す」というしくみで、デプロイとステージは一対多の関係にあります。
つまりステージよりもデプロイの方が大元の概念です。

実際、マネジメントコンソールコンソールでAPIのデプロイを作成するとき、「ステージなし」デプロイを作成できます。

個人的には、本来は「デプロイ履歴」の画面がある方が自然だと思いますが、前述のとおり、現時点では残念ながらマネジメントコンソールには存在せず、「ステージ」画面から間接的にデプロイ履歴の一覧を確認できるのみとなります。
（とあるスポーツリーグで、リーグのチーム一覧を、各選手のプロフィール画面の『所属チーム』の画面からしか見られない、というような状態。）

参考

aws apigateway update-deploymentコマンド

デプロイの説明文を変更する際に使用するコマンドです。

https://awscli.amazonaws.com/v2/documentation/api/latest/reference/apigateway/update-deployment.html

--patch-operationsで指定する属性と値について

aws apigateway update-deploymentでは、op=replace,path=/descriptionの組み合わせのみ、指定できます：

https://docs.aws.amazon.com/apigateway/latest/api/patch-operations.html#UpdateDeployment-Patch

（補足）API GatewayのAPI Reference

aws apigateway get-deploymentコマンド

特定のデプロイの情報を確認する際に使用するコマンドです。

https://awscli.amazonaws.com/v2/documentation/api/latest/reference/apigateway/get-deployment.html

aws apigateway get-deploymentsコマンド

デプロイ情報の一覧を確認する際に使用するコマンドです。

https://awscli.amazonaws.com/v2/documentation/api/latest/reference/apigateway/get-deployments.html

--input-cli-jsonオプションに指定するパラメータについて

--input-cli-jsonオプションにJSONファイルを指定する場合、そのパスにfile://プレフィックスを付ける必要があります。

  1. Run the command with the completed parameters by passing the completed template file to either the --cli-input-json or --cli-input-yaml parameter by using the file:// prefix. The AWS CLI interprets the path to be relative to your current working directory, so in the following example that displays only the file name with no path, it looks for the file directly in the current working directory.

https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-skeleton.html

このページへのリンクは各コマンドのドキュメントページの--input-cli-jsonオプションのところに掲載されていないので、わかりづらいです。「--input-cli-jsonオプションの説明は、独立したページがある」ということを覚えておくとよいでしょう。

ちなみに、--input-cli-jsonオプションには、JSON文字列をシングルクォート'で囲った文字列を直接パラメータとして指定できますが、取り回ししづらいですしミスの元なので、素直にJSONファイルを作成しましょう。

Discussion