Amazon Web Services ブログ
新しい Amazon API Gateway Portal で API の発見性を向上させる
本記事は 2025年11月19日に公開された「Improve API discoverability with the new Amazon API Gateway Portal」を翻訳したものです。
Amazon API Gateway は、フルマネージドなポータル機能である Amazon API Gateway Portal を提供開始しました。これにより、静的ウェブサイト、オープンソースソリューション、またはサードパーティ製品を使用する必要がなくなります。これらの従来の方法は、API ライフサイクル管理の断片化やコスト増加につながることがよくありました。API Gateway Portal は API Gateway サービスと統合され、API 製品、インタラクティブな「Try it」機能、API ポートフォリオのドキュメントなどの機能を提供します。
このフルマネージドソリューションは、API を紹介し、開発者が迅速に API を見つけ、試し、統合できるシームレスな方法の必要性に対応します。インフラストラクチャ、セキュリティ、スケーラビリティを処理するマネージドソリューションを提供することで、API プロバイダーは価値ある API の作成と優れた開発者エクスペリエンスの提供に集中できます。
本記事では、新しいポータル機能を使用して、インフラストラクチャを管理することなく、複数のアカウントからの API を使用して、強化されたセキュリティ機能を備えたカスタマイズ可能なポータルを数分で作成する方法を紹介します。
概要
開発者ポータルは、API プロバイダーが API と API ドキュメントをポータル製品にグループ化して共有できる Web ページです。各ポータル製品は REST API の論理的なグループであり、API コンシューマー向けに作成および公開するドキュメントが含まれています。ポータル内の製品ページには、ポータル製品レベルでのカスタムドキュメントが含まれています。製品 REST エンドポイントページには、REST API のパスとメソッドの詳細、およびデプロイされているステージを含む、各 REST API のドキュメントが含まれています。製品ページ と製品 REST エンドポイント ページの組み合わせにより、API コンシューマーに REST API の使用開始方法に関する完全なドキュメントを提供します。
この抽象化により、複数の API とステージからのエンドポイントを、コンシューマー向けの一貫性のあるプロダクト提供に整理できます。たとえば、ペット養子縁組サービスをサポートする複数の API を運用している場合、ある API からの犬関連エンドポイントと別の API からの猫関連エンドポイントをグループ化した「AdoptAnimals」ポータルプロダクトを作成し、ユーザー管理機能を別の「AdoptProcess」ポータルプロダクトに整理できます。
この柔軟性により、技術アーキテクチャではなくビジネスロジックに合わせて API を提示し、コンシューマーにとって最も意味のある方法で API を整理できます。広範な API ポートフォリオを管理する大企業の場合、API Gateway Portal は事業グループ全体で API の一元化されたカタログを提供し、重複作業を削減し、標準化を改善します。
ポータル機能は、ドキュメント、インタラクティブなテスト機能、統合されたコンシューマー分析を備えた API を表示する開発者ポータルを自動的に作成します。このプラットフォームは、マルチアカウント API 共有に AWS Resource Access Manager (RAM)、アクセス制御に Amazon Cognito、一元化された監視に Amazon CloudWatch を使用します。
API Gateway Portal の主な機能
API Gateway Portal は、API プロバイダーとコンシューマーの両方に包括的な機能を提供します。
以下は、サービスのローンチ時に導入された主な機能のリストです。
カスタマイズ可能なポータルエクスペリエンス：カスタムロゴとカラースキームを通じてポータルのブランディングを制御できます。AWS Certificate Manager で管理される SSL 証明書を使用してカスタムドメイン名を設定するか、AWS が提供するデフォルトのドメイン構造を使用できます。
柔軟なアクセス制御：開発者ポータルへのアクセスは Amazon Cognito を使用して制御でき、ポータルを公開アクセス可能にするか、認証を要求するかを設定できます。Cognito ユーザープールとの統合により、エンタープライズグレードで費用対効果が高く、カスタマイズ可能な安全でスケーラブルな ID およびアクセス管理が提供されます。既存の ID システムを使用している組織の場合、Cognito は SAML および OpenID Connect ID プロバイダーとのフェデレーションをサポートしています。
クロスアカウント API 組織化：ポータルは AWS RAM を使用したクロスアカウントでのポータル製品の共有をサポートしているため、組織は統一された API カタログを作成しながら、API プロバイダーが独自のアカウントで API を開発および維持する柔軟性を維持できます。ポータル製品を別のアカウントと共有する場合、そのアカウントはポータル製品または製品エンドポイントページのプロパティを変更できないため、API プロバイダーは組織全体での発見を可能にしながら、API の制御を維持します。クロスアカウント共有機能は、一元化された発見、標準化、重複の削減、明確な所有権、制御されたアクセスなど、エンタープライズ顧客に重要なガバナンス上の利点を提供します。
ドキュメント：API 定義から同期された API リファレンスドキュメントに加えて、ガイド、ユースケース、統合例などの補足ドキュメントを追加できます。
検索、発見、インタラクティブな API 探索：コンシューマーはカタログ全体を検索できます。ポータルは、ユーザーがニーズに合った適切なエンドポイントを見つけるのに役立つ、直感的でカスタマイズ可能なナビゲーションと組織化を提供します。「Try it」機能を使用すると、コンシューマーはポータルから直接 API を試すことができます。ユーザーはリクエストパラメータ、ヘッダーを入力し、ライブレスポンスを確認できるため、API 統合の価値実現までの時間が短縮されます。この環境には、セキュリティとコスト管理のための組み込み制限が含まれています。
アクセス制御とガバナンス
Amazon API Gateway Portal は、本番環境のデプロイに不可欠なセキュリティとガバナンス機能を提供します。
ID およびアクセス管理：Cognito ユーザープールとの統合により、多要素認証、パスワードポリシー、ユーザーライフサイクル管理を含む、エンタープライズグレードで費用対効果が高く、カスタマイズ可能な安全でスケーラブルな ID およびアクセス管理が提供されます。
API 認可：ポータルは、AWS IAM、Lambda オーソライザー、Cognito ユーザープールなど、API に設定された既存の認可メカニズムを尊重します。ポータルアクセスは、確立されたセキュリティ制御をバイパスしません。
クロスアカウントガバナンス：AWS RAM を使用してアカウント間でポータル製品を共有する場合、元の API 所有者は、認可戦略、統合設定、ステージ設定を含む、エンドポイントの完全な制御を保持します。ポータル所有者は共有されたポータル製品を使用できますが、基盤となる API 設定を変更することはできません。
監査とモニタリング：すべてのポータル管理アクティビティは、包括的な監査ログのために AWS CloudTrail と統合されます。Amazon CloudWatch RUM を使用して、リアルユーザーモニタリングを実行し、API コンシューマーに関する分析をほぼリアルタイムで収集および表示できます。
リソース制限：このサービスには、API テストのレート制限、ペイロードサイズ、統合タイムアウトの制限など、悪用を防ぐための組み込みクォータが含まれています。これらの制限により、「Try it」機能が本番環境の API パフォーマンスに影響を与えることはありません。
開始方法
ポータルのセットアップには、ポータル製品の作成、ポータルの設定、コンシューマーアクセスのための公開という 3 つの主なステップがあります。これらのステップを詳しく見ていきます。
ポータル製品の作成
以下の手順は、ポータル製品を作成する方法を示しています。
- API Gateway コンソールに移動し、メインナビゲーションからポータル製品を選択します。
- ポータル製品の作成を選択し、名前、説明、可視性設定を含むポータル製品の詳細を指定します。
- 次に、このポータル製品に含めるエンドポイントを選択します。API ステージ全体、または特定のリソースとメソッドを選択でき、発見性を向上させるためにユーザーフレンドリーな名前でエンドポイントの名前を変更することもできます。
- システムは API ドキュメントを自動的にインポートします。後で追加のコンテキスト、ユースケース、例を使用してドキュメントを改善できます。
- 技術的な実装の詳細ではなく、ビジネスロジックを反映するカスタムカテゴリに製品エンドポイントを整理します。
開発者ポータルの設定
以下の手順は、ポータルを作成する方法を示しています。
- API Gateway コンソールのナビゲーションで開発者ポータルを選択します。
- ポータル名、説明、ドメイン設定を指定します。
- デフォルトの AWS ドメインにプレフィックスを追加するか、独自の SSL 証明書を使用してカスタムドメイン名を設定するかを選択します。
- 認証要件を選択してアクセス制御を設定します。内部ポータルの場合は Amazon Cognito 認証を要求し、公開ポータルの場合はドキュメントへの匿名アクセスを許可できます。
- ロゴをアップロードし、ブランドアイデンティティに合わせてカラーテーマを選択します。
- ポータル製品を追加します。自分のアカウントからの製品、または AWS RAM を通じて他のアカウントから共有された製品を含めることができます。ポータルは、コンシューマー向けの検索とフィルタリング機能を提供します。
プレビューと公開
ポータルを公開する前に、プレビュー機能を使用してコンシューマーエクスペリエンスを確認します。プレビューには、ナビゲーション、ドキュメント、利用可能な API テスト機能など、ポータルがユーザーにどのように表示されるかが正確に表示されます。
設定に満足したら、ポータルの公開を選択してコンシューマーがアクセスできるようにします。公開プロセスは通常数分以内に完了し、API Gateway はコンシューマーに配布するための最終的なポータル URL を提供します。
まとめと次のステップ
新しい API Gateway Portal は、カスタム API ドキュメントサイトの構築と維持の複雑さを排除します。開発者は、API をすぐに発見して試すことができる、プロフェッショナルで機能豊富なエクスペリエンスを得られます。さらに、すべてが AWS 内に留まるため、CloudWatch や CloudTrail などのサービスとの統合により、組み込みのセキュリティ、簡素化された運用、包括的な可観測性が得られます。
API 発見エクスペリエンスを合理化する準備はできましたか？開始方法は次のとおりです。
- API Gateway コンソールにアクセスして、最初のポータルを作成します
- 開発者ガイドのステップバイステップのチュートリアルに従います
- Serverless Land で API 開発の詳細を学びます