この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
いわさです。
API Gateway は OpenAPI / Swagger定義ファイルをインポートすることが出来ます。
APIドキュメントにはドキュメントパーツというリソースがあり、APIエンティティに提供されるドキュメントコンテンツを定義出来ます。
今回、動的パスに関するドキュメントを大量に作成してインポートしたところ、「ドキュメントパーツの制限を超えた」というエラーメッセージを受信しました。
この記事ではこの制限の確認と解決方法について紹介します。
ドキュメントパーツ
以下のようにx-amazon-apigateway-documentationでドキュメントパーツを定義することが出来ます。
{
"swagger" : "2.0",
"info" : {
"version" : "2022-05-26T01:07:59Z",
"title" : "pats1"
},
"host" : "cvm5zxkwhh.execute-api.ap-northeast-1.amazonaws.com",
"basePath" : "/hoge",
"schemes" : [ "https" ],
"paths" : {
:
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "v1",
"createdDate" : "2022-05-26T01:16:11Z",
"documentationParts" : [ {
"location" : {
"type" : "MODEL",
"name" : "Empty"
},
"properties" : {
"title" : "Empty Schema"
}
}, {
"location" : {
"type" : "RESOURCE",
"path" : "/1"
},
"properties" : {
"description" : "1"
}
}, {
"location" : {
"type" : "RESOURCE",
"path" : "/2"
},
"properties" : {
"description" : "2"
}
}, {
"location" : {
"type" : "RESPONSE",
"method" : "GET",
"statusCode" : "200"
},
"properties" : {
"description" : "200 response"
}
} ]
}
}そして、API Gatewayコンソールからこのドキュメントをインポートすることが出来ます。
大量パーツとエラー
今回、以下のようにドキュメントパーツ部分が2500ほどになりました。
一点注意点があって、この記事ではドキュメント設計としての良し悪しについて言及するものではないので、そもそも大量のドキュメントパーツを定義するべきではないみたいなところは言及しません。こういったエラーが起きたときにドキュメントを見直す以外にどういう対処をしたら良いのかを紹介したいと思っています。
パーツ2500件
{
"swagger" : "2.0",
"info" : {
"version" : "2022-05-26T01:07:59Z",
"title" : "pats1"
},
"host" : "cvm5zxkwhh.execute-api.ap-northeast-1.amazonaws.com",
"basePath" : "/hoge",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "https://classmethod.jp/",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
}
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "v1",
"createdDate" : "2022-05-26T01:16:11Z",
"documentationParts" : [
{"location" : {"type" : "RESPONSE", "method" : "GET", "statusCode" : "200"}, "properties" : {"description" : "200 response"}},
{"location" : {"type" : "MODEL", "name" : "Empty"}, "properties" : {"title" : "Empty Schema"}},
{"location" : {"type" : "RESOURCE", "path" : "/1"}, "properties" : {"description" : "1"}},
{"location" : {"type" : "RESOURCE", "path" : "/2"}, "properties" : {"description" : "2"}},
{"location" : {"type" : "RESOURCE", "path" : "/3"}, "properties" : {"description" : "3"}},
{"location" : {"type" : "RESOURCE", "path" : "/4"}, "properties" : {"description" : "4"}},
{"location" : {"type" : "RESOURCE", "path" : "/5"}, "properties" : {"description" : "5"}},
:
{"location" : {"type" : "RESOURCE", "path" : "/2497"}, "properties" : {"description" : "2497"}},
{"location" : {"type" : "RESOURCE", "path" : "/2498"}, "properties" : {"description" : "2498"}},
{"location" : {"type" : "RESOURCE", "path" : "/2499"}, "properties" : {"description" : "2499"}},
{"location" : {"type" : "RESOURCE", "path" : "/2500"}, "properties" : {"description" : "2500"}}
]
}
}この大量のドキュメントパーツを含むドキュメントをインポートしてみます。
思ってたよりインポートの結果が出る時間はかからないです。
私が確認した際には画面上はエラー通知も完了通知も何も表示されませんでした。しかし取り込みはされていません。
CloudTrailを見てみると、エラー内容を確認することが出来ます。
以下のエラーが発生しています。
Warnings found during import:
Unable to import documentation parts from the Swagger file because it contains more documentation parts than the maximum number allowed for this API. Please contact AWS if you need additional documentation parts.
{
"eventVersion": "1.08",
"userIdentity": {
:
},
"eventTime": "2022-05-26T01:30:49Z",
"eventSource": "apigateway.amazonaws.com",
"eventName": "ImportDocumentationParts",
"awsRegion": "ap-northeast-1",
"sourceIPAddress": "AWS Internal",
"userAgent": "AWS Internal",
"errorCode": "BadRequestException",
"errorMessage": "Warnings found during import:\n\tUnable to import documentation parts from the Swagger file because it contains more documentation parts than the maximum number allowed for this API. Please contact AWS if you need additional documentation parts.",
"requestParameters": {
"omitted": true,
"originalSize": 883383,
"reason": "requestParameters too large"
},
"responseElements": null,
"requestID": "1228b1b0-47ab-4163-a2a8-af381d9d0c8e",
"eventID": "b68e623d-4747-4a19-9696-a4148839354c",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"sessionCredentialFromConsole": "true"
}原因と対策
上記のエラー内容からインポートしようとしているドキュメントパーツの上限に達したようです。
この上限値についてはドキュメントへも記載があります。
「REST API の設定および実行に関する API Gateway クォータ」へ以下のように記載があります。
最大が2000であること、引き上げ可能であることがわかりました。
| リソースまたはオペレーション | デフォルトのクォータ | 引き上げ可能 |
|---|---|---|
| API あたりのドキュメント部分 | 2000 | はい |
試しに1990個くらいにドキュメントパーツの数を削った場合は正常に取り込まれたので、このリミットが正しいようです。
API あたりのすべてのクォータは、特定の API でのみ引き上げることができます。
とあるので、デフォルトが2000であることを引き上げることは出来なくて、APIごとに上限緩和申請を行う必要があります。
サービスクォーターからの上限緩和依頼は出来ない
さて、それでは上限緩和申請をして引き上げを行いたいところですが、どうやらAPI GatewayのAPIリソースごとの上限緩和はサービスクォータでは対応していないようです。
サポートケースから上限緩和申請
サポートケースを起票し、上限緩和申請を行います。
サポートケースの起票手順などは割愛しますが、以下のようにサービスクォータが利用出来てサポートケースの起票が出来ないケースもあるので、アカウントの管理者の方へ確認してください。
上限緩和後、インポートしてみる
上限緩和されたあとに、再度取り込んでみます。
無事インポート出来ました。2500件でしたが、あまりインポート時間かかりませんでしたね。
ただし、API Gatewayのドキュメントページではスクロールバー付きで全件表示されます。こちらのレンダリングがちょっと重たい感じがするかもしれませんのでご注意ください。
さいごに
本日はAPI Gatewayのドキュメントパーツ上限を緩和した上で、大量のドキュメントパーツを取り込んでみました。
同様のエラーメッセージでインポート出来なかった方の参考になれば嬉しいです。
ハードリミット情報は公開されていませんが、無限に緩和出来るわけではないので、「ドキュメントパーツ数多いけどこれでいいのか？」という立ち止まりは、それはそれでしてみてください。
25
