Amazon API Gateway の API キーと使用量プランを AWS CLI だけで操作してみた

いわさです。

Amazon API Gateway では API キーを使って使用量を測定したりスロットリングを設定したりすることが出来ます。
しかし、標準の API キーや使用量プランで満たせないものは別の仕組みで作り込みや自動化が必要になる場合があります。

例えば、標準 API キーには API の使用期限などを設けることは出来ないので、有効期限を独自に管理して自動で API キーの無効化や削除を行う必要があります。
今後そのあたりの方法を紹介したいと思いますが、独自の作り込みを行う際には前もって AWS CLI などで一通りの自動化操作で行いたい内容を試しておくと実現性が確認出来たり、必要なパラメータを抑えることが出来ます。

そこで今回は API キーと使用量プラン関係の操作を AWS CLI から行ってみましたので実行方法などを紹介します。
ちなみに API キーと使用量プランはアカウント内の対象リージョン内で共通で使用が可能です。リージョンが違うと利用出来ません。

REST API 作成

今回は API は既に作成済みで、かつ適当なステージにデプロイ済みとします。

使用量プラン作成

今回 AWS CLI で実際に試してみてわかったのですが、流れとしては使用量プランを作成して API キーを作成し、使用量プランに API キーを関連付けるという形で数ステップ必要でした。
インポートだとまとめて作成から関連付けまで出来そうですが、今回は個別のキー作成を行いたいのでインポートは無しで行きます。

使用量プランの作成は次のコマンドで実行出来ます。
この作成のタイミングで対象の API ステージを指定することで使用量プランとステージの関連付けが出来ます。

create-usage-plan — AWS CLI 1.27.75 Command Reference

% cat create-usage-plan-apistaeges.json
[
  {
    "apiId": "xfwfkbc1m6",
    "stage": "hogestage"
  }
]
% aws apigateway create-usage-plan --name hogeusage1 --api-stages file://create-usage-plan-apistaeges.json
{
    "id": "5aqdog",
    "name": "hogeusage1",
    "apiStages": [
        {
            "apiId": "xfwfkbc1m6",
            "stage": "hogestage"
        }
    ]
}

ステージの関連付けされた状態で使用量プランが作成されていますね。

API キー作成

続いて API キーを作成しましょう。
API キー作成は次のコマンドで実行で来ます。

create-api-key — AWS CLI 1.27.75 Command Reference

stageKeysのパラメータが存在しますが DEPRECATED となっており、ステージの関連付けは使用量プランに任せる形が良さそうです。

% aws apigateway create-api-key --name hoge0220key1 --value hoge0220xxxxxxxxxxxxxxxxxxxx01
{
    "id": "6nbtwoyd18",
    "value": "hoge0220xxxxxxxxxxxxxxxxxxxx01",
    "name": "hoge0220key1",
    "enabled": false,
    "createdDate": "2023-02-20T17:03:43+09:00",
    "lastUpdatedDate": "2023-02-20T17:03:43+09:00",
    "stageKeys": []
}

valueパラメータは任意で、指定しなかった場合はランダムでキー値が自動生成されます。

% aws apigateway create-api-key --name hoge0220key2
{
    "id": "3q590w9bu1",
    "value": "PCAjFs0a82sRiwBqOozx8nvVEZjV7F81TUQACFx3",
    "name": "hoge0220key2",
    "enabled": false,
    "createdDate": "2023-02-20T17:23:01+09:00",
    "lastUpdatedDate": "2023-02-20T17:23:01+09:00",
    "stageKeys": []
}

また、デフォルトでは enabled が false であることに注意してください。
この状態だと使用量プランに関連付けしたとしても API キーを利用することは出来ません。

次のようにenabledフラグを付与しましょう。

% aws apigateway create-api-key --name hoge0220key3 --value hoge0220xxxxxxxxxxxxxxxxxxxx03 --enabled
{
    "id": "xapperbfej",
    "value": "hoge0220xxxxxxxxxxxxxxxxxxxx03",
    "name": "hoge0220key3",
    "enabled": true,
    "createdDate": "2023-02-20T17:32:28+09:00",
    "lastUpdatedDate": "2023-02-20T17:32:28+09:00",
    "stageKeys": []
}

ただし、この時点では Enable 状態でも使用量プランに関連付いていないため API キーを使って API を呼び出すことはまだ出来ません。もう１ステップ必要です。

% curl -H "x-api-key:hoge0220xxxxxxxxxxxxxxxxxxxx03" https://xfwfkbc1m6.execute-api.ap-northeast-1.amazonaws.com/hogestage
{"message":"Forbidden"}

API キーと使用量が関連づいてない

前述のとおり API キーは作成しただけだと使用量プランとの関連付けはされていません。
そこで、次のコマンドを使って作成した API キーを使用量プランに関連付けすることが出来ます。

create-usage-plan-key — AWS CLI 1.27.75 Command Reference

必要な入力値は使用量プランの ID と API キーの ID です。
key-typeはAPI_KEYのみ受け付けるようです。

% aws apigateway create-usage-plan-key --usage-plan-id 5aqdog --key-id 6nbtwoyd18 --key-type API_KEY
{
    "id": "6nbtwoyd18",
    "type": "API_KEY",
    "value": "hoge0220xxxxxxxxxxxxxxxxxxxx01",
    "name": "hoge0220key1"
}

ここまで来ると、API キーで対象ステージの API が呼び出せるはずです。

% curl -H "x-api-key:hoge0220xxxxxxxxxxxxxxxxxxxx01" https://xfwfkbc1m6.execute-api.ap-northeast-1.amazonaws.com/hogestage
hoge mock response

使用量取得

さて、少しタイムラグがありますが、AWS CLI からも使用量を取得することが出来ます。
使用量プラン ID を指定して取得出来ますが、追加の条件として API キー ID も指定することが出来ます。

get-usage — AWS CLI 1.27.75 Command Reference

% aws apigateway get-usage --usage-plan-id 5aqdog --start-date 2023-02-18 --end-date 2023-02-20                    
{
    "items": {
        "6nbtwoyd18": [
            [
                0,
                0
            ],
            [
                0,
                0
            ],
            [
                2,
                0
            ]
        ],
        "xapperbfej": [
            [
                0,
                0
            ],
            [
                0,
                0
            ],
            [
                1,
                0
            ]
        ]
    },
    "usagePlanId": "5aqdog",
    "startDate": "2023-02-18",
    "endDate": "2023-02-20"
}
% aws apigateway get-usage --usage-plan-id 5aqdog --start-date 2023-02-18 --end-date 2023-02-20 --key-id 6nbtwoyd18
{
    "items": {
        "6nbtwoyd18": [
            [
                0,
                0
            ],
            [
                0,
                0
            ],
            [
                2,
                0
            ]
        ]
    },
    "usagePlanId": "5aqdog",
    "startDate": "2023-02-18",
    "endDate": "2023-02-20"
}

また、使用量データは次のコマンドで更新することも出来るようです。試してみましょうか。

update-usage — AWS CLI 1.27.75 Command Reference

% aws apigateway update-usage --usage-plan-id 5aqdog --key-id 6nbtwoyd18 --patch-operations op="replace",path="/remaining",value="50"

An error occurred (BadRequestException) when calling the UpdateUsage operation: Cannot update usage because Usage Plan 5aqdog does not have quota enabled
% aws apigateway update-usage --usage-plan-id 5aqdog --key-id 6nbtwoyd18 --patch-operations op="replace",path="/used",value="50"

An error occurred (BadRequestException) when calling the UpdateUsage operation: Cannot update usage because Usage Plan 5aqdog does not have quota enabled

エラーになりました。
どうやら使用量プランのクォーター機能を有効化していない場合は更新出来ないようです。
使用量プラン作成時にクォーターパラメータを省略したため、何も設定されていない状態になっていました。

クォーターが有効な状態でもう一度確認してみましょう。

% aws apigateway update-usage --usage-plan-id 5aqdog --key-id 6nbtwoyd18 --patch-operations op="replace",path="/used",value="10" 

An error occurred (BadRequestException) when calling the UpdateUsage operation: Invalid patch path  '/used' specified for op 'replace'. Must be one of: [/remaining]
% aws apigateway update-usage --usage-plan-id 5aqdog --key-id 6nbtwoyd18 --patch-operations op="replace",path="/remaining",value="10"
{
    "usagePlanId": "5aqdog",
    "startDate": "2023-02-20",
    "endDate": "2023-02-20",
    "items": {
        "6nbtwoyd18": [
            [
                2,
                10
            ]
        ]
    }
}

どうやら更新出来るのは残回数だけのようですね。
更新対象日付の指定も出来ないので対象は最新の残回数が更新されるようです。

API キー削除

最後に API キーの削除を行ってみます。
作成の時は API キーを作成して使用量プランに関連付けするという２ステップが必要でした。

削除時もまず同じ方法を行ってみます。
次のコマンドで使用量プランからの関連付けが解除されます。Deleteという表現が使われていますが API キー自体の削除はされません。

delete-usage-plan-key — AWS CLI 1.27.75 Command Reference

% aws apigateway delete-usage-plan-key --usage-plan-id 5aqdog --key-id 6nbtwoyd18

さらに、API キー自体の削除は次のコマンドで行います。

delete-api-key — AWS CLI 1.27.75 Command Reference

% aws apigateway delete-api-key --api-key 6nbtwoyd18

これで API キーが削除されました。

使用量プランに関連づいた状態でも API キーは削除出来る

先程は使用量プランからの解除を行ってから削除を行いました。
2 ステップ実行せずに使用量プランに紐付いている状態で消せるかも確認してみます。

% aws apigateway delete-api-key --api-key xapperbfej

問題なく削除が出来ました。

さいごに

本日は Amazon API Gateway の API キーと使用量プランを AWS CLI だけで操作してみました。

今回一通りの流れを AWS CLI でシミュレーション出来たので、アプリケーションに機能として取り込むことは問題なく出来そうだなということが確認出来ました。
また、実際に現在アプリケーションの作成を行っているのですが、SDK 利用時に必須パラメータ何が必要かを今回の検証結果からすぐに確認出来たり、あるいはデフォルト無効化なので明示的に有効化フラグが必要など、情報が事前に整理出来るので CLI や API で事前検証するのは中々お勧めです。