サーバーレス開発者ポータルを使用して API Gateway API を分類する - Amazon API Gateway
開発者ポータルを作成する開発者ポータルの設定開発者ポータルの管理者ユーザーを作成する開発者ポータルのユーザーの管理開発者ポータルに API Gateway マネージド型 API を発行するAPI Gateway マネージド型 API の更新または削除非 API Gateway マネージド型 API を削除するには開発者ポータルに非 API Gateway マネージド型 API を発行するお客様が開発者ポータルを使用する方法開発者ポータルのベストプラクティス

サーバーレス開発者ポータルを使用して API Gateway API を分類する

開発者ポータルは、API を顧客が利用できるようにするために使用するアプリケーションです。サーバーレス開発者ポータルを使用して API Gateway から直接 API Gateway マネージド型 API を公開できます。OpenAPI 定義をアップロードすることで、非 API Gateway マネージド型 API を公開することもできます。サーバーレス開発者ポータルで API を公開すると、顧客は簡単に次のことができます。

  • どの API が利用可能かをご確認ください。

  • API ドキュメントを参照してください。

  • 登録すると — すぐに、アプリケーションの構築に使用できる独自の API キーを受け取る — ことができます。

  • 開発者ポータル UI で API をお試しください。

  • 独自の API の使用状況をモニタリングします。

Amazon API Gateway は、定期的に更新されるサーバーレス開発者ポータルアプリケーションを AWS Serverless Application Repository および GitHub で公開します。これは Apache 2.0 ライセンスのもとでリリースされ、カスタマイズしてビルドおよびデプロイツールに組み込むことができます。フロントエンドは React で記述されており、完全にカスタマイズ可能になるよう設計されています。https://github.com/awslabs/aws-api-gateway-developer-portal/wiki/Customization を参照してください。

AWS Serverless Application Repository の詳細については、「AWS Serverless Application Repository 開発者ガイド」を参照してください。

ヒント

サーバーレス開発者ポータルのサンプルをお試しになる場合は、https://developer.exampleapigateway.com/ を参照してください。

開発者ポータルを作成する

API Gateway サーバーレス開発者ポータルは、ブランドに合うように、そのまま、またはカスタマイズしてデプロイできます。開発者ポータルをデプロイするには、次の 2 つの方法があります。

  • AWS Serverless Application Repository を使用する。[デプロイ] ボタンを選択し、API Gateway サーバーレス開発者ポータル AWS CloudFormation スタックを起動して、Lambda コンソールで多数のスタックパラメータを入力します。

  • AWS GitHub リポジトリから API Gateway サーバーレス開発者ポータルをダウンロードし、AWS SAM CLI から API Gateway サーバーレス開発者ポータル AWS CloudFormation スタックを起動します。

AWS Serverless Application Repository を使用してサーバーレス開発者ポータルをデプロイするには

  1. AWS Serverless Application Repository の API Gateway サーバーレス開発者ポータルページに移動します。

  2. [デプロイ] を選択します。

    注記

    AWS Lambda コンソールへのサインインが求められる場合があります。

  3. Lambda コンソールで、[アプリケーションの設定] で必要な開発者ポータルスタックパラメータを入力します。

    注記

    S3 バケット名と Amazon Cognito ドメインプレフィックスが必要です。その他の設定はオプションです。

  4. [Got an opinion? (ご意見をお聞かせください)] 顧客フィードバックボタンを有効にする場合は、以下を実行する必要があります。

    • [DevPortalAdminEmail] ボックスに E メールアドレスを入力します。顧客がフィードバックを送信すると、E メールがこのアドレスに送信されます。

      注記

      E メールアドレスを指定しないと、[Got an opinion? (ご意見をお聞かせください)] は開発者ポータルに表示されません。

    • 必要に応じて、[DevPortalFeedbackTableName] ボックスにテーブル名を入力します。デフォルトの名前は "DevPortalFeedback" です。顧客がフィードバックを送信すると、この名前の DynamoDB テーブルにフィードバックが保存されます。

  5. [I acknowledge that this app creates custom IAM roles and resource policies (このアプリでカスタム IAM ロールおよびリソースポリシーを作成することを認識しています)] チェックボックスをオンにします。

  6. [デプロイ] を選択します。

  7. [AdminEmail] スタックパラメータに E メールアドレスを入力した場合、Amazon SNS サブスクリプション E メールがその E メールアドレスに送信されます。この E メールは、[MarketplaceSubscriptionTopicProductCode] 設定で指定した Amazon SNS トピックへのサブスクリプションを確認します。

AWS SAM を使用してサーバーレス開発者ポータルをダウンロードおよびデプロイするには

  1. 最新の AWS CLIと AWS SAMCLI がインストールされ、設定されていることを確認します。

  2. API Gateway サーバーレス開発者ポータルリポジトリをダウンロードまたはクローンします。

  3. 圧縮された Lambda 機能をアップロードできるプライベート Amazon S3 バケットがあることを確認します。ない場合は、Amazon S3 コンソールまたは CLI を使用して作成できます。

    AWS SAM CLI で、{your-lambda-artifacts-bucket-name} を Amazon S3 バケットの名前に置き換えてプロジェクトのルートで次のコマンドを実行します。 

    sam package --template-file ./cloudformation/template.yaml \
    --output-template-file ./cloudformation/packaged.yaml \
    --s3-bucket {your-lambda-artifacts-bucket-name}

  4. このステップについては、--parameter-overrides の 開発者ポータルの設定 (CognitoDomainNameOrPrefix など) のパラメータの詳細を参照してください。

    注記

    AWS SAM テンプレートをアップロードするためのプライベート Amazon S3 バケットがあることを確認してください (AWS CloudFormation は開発者ポータルをデプロイするためにバケットからテンプレートを読み込みます)。 これは、zip 形式の Lambda 関数をアップロードするために前のステップで指定したバケットと同じ場合があります。

    以下のように置き換えて、プロジェクトルートから以下のコマンドを実行します。

    • Amazon S3 バケットの名前を使用した {your-template-bucket-name}

    • グローバルに一意なプレフィックスを使用した {custom-prefix}

    • {cognito-domain-or-prefix} を一意の文字列に置き換えます。 

    sam deploy --template-file ./cloudformation/packaged.yaml \
    --s3-bucket {your-template-bucket-name} \
    --stack-name "{custom-prefix}-dev-portal" \
    --capabilities CAPABILITY_NAMED_IAM \
    --parameter-overrides CognitoDomainNameOrPrefix= "{cognito-domain-or-prefix}" DevPortalSiteS3BucketName="{custom-prefix}-dev-portal-static-assets" ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts"

開発者向けポータルが完全にデプロイされたら、以下のようにその URL を取得できます。

新しく作成した開発者ポータルの URL を取得するには

  1. AWS CloudFormation コンソールを開きます。

  2. スタックの名前 (aws-serverless-repository-api-gateway-dev-portal がデフォルトのスタック名です) を選択します。

  3. Outputs セクションを開きます。開発者ポータルの URL は WebsiteURL プロパティで指定します。

開発者ポータルの設定

以下は、開発者ポータルのデプロイ中およびデプロイ後に設定する必要がある設定です。

注記

以下の設定の多くは、開発者ポータルをデプロイした後で AWS CloudFormation スタックを更新することによって変更できます。詳細については、「AWS CloudFormation スタックの更新」を参照してください。

[ArtifactsS3BucketName (必須)]

デプロイプロセスにより、カタログのメタデータが保存されるプライベートアクセス可能な Amazon S3 バケットが作成されます。バケットに割り当てる名前を指定します。この名前はグローバルに一意である必要があります。

[CognitoDomainNameOrPrefix (必須)]

この文字列を Amazon Cognito でホストされた UI と組み合わせて、ユーザーのサインアップとサインインのために使用します。一意のドメイン名またはプレフィックス文字列を指定します。

[CognitoIdentityPoolName]

デプロイプロセスによって Amazon Cognito ID プールが作成されます。ID プールのデフォルト名は、[DevPortalIdentityPool] です。

[CustomDomainNameAcmCertArn]

ACM 証明書に関連付けられたドメイン名を指定した場合は、ここで ACM 証明書の ARN も指定する必要があります。カスタムドメイン名なしで開発者ポータルを作成する場合は、ここを空白のままにします。

[DevPortalAdminEmail]

E メールアドレスを指定して、[Got an opinion? (ご意見をお持ちですか?)] お客様からのフィードバックボタンを有効にします。顧客がフィードバックを送信すると、E メールがこのアドレスに送信されます。

注記

E メールアドレスを指定しないと、[Got an opinion? (ご意見をお聞かせください)] ボタンは開発者ポータルに表示されません。

[DevPortalFeedbackTableName]

[DevPortalAdminEmail] に E メールアドレスを指定した場合、デプロイプロセスにより DynamoDB テーブルが作成され、顧客が入力したフィードバックが保存されます。デフォルトの名前は "DevPortalFeedback" です。オプションで独自のテーブル名を指定できます。

[DevPortalCustomersTableName]

デプロイプロセスでは、顧客アカウントが保存される DynamoDB テーブルが作成されます。オプションでこのテーブルに割り当てる名前を指定できます。名前はアカウントとリージョン内で一意である必要があります。テーブルのデフォルト名は、[DevPortalCustomers] です。

[DevPortalSiteS3BucketName (必須)]

デプロイプロセスにより、ウェブアプリケーションコードが保存されるプライベートアクセス可能な Amazon S3 バケットが作成されます。このバケットに割り当てる名前を指定します。この名前はグローバルに一意である必要があります。

[MarketplaceSubscriptionTopicProductCode]

これは、サブスクライブ/サブスクライブ解除イベントの Amazon SNS トピックのサフィックスです。任意の値を入力します。デフォルト値は DevPortalMarketplaceSubscriptionTopic です。この設定は AWS Marketplace 統合を使用している場合にのみ関連します。詳細については、「新しいお客様を受け入れるように SaaS 製品を設定する」を参照してください。

[StaticAssetRebuildMode]

デフォルトでは、静的アセットの再ビルドによりカスタムコンテンツは上書きされません。カスタムコンテンツをローカルバージョンに置き換えるには、overwrite-content を指定します。

重要

overwrite-content を指定すると、Amazon S3 バケットのすべてのカスタム変更は失われます。実行内容を理解していない場合、これを実行しないでください。

[StaticAssetRebuildToken]

開発者ポータルサイトの静的アセットを再アップロードするために、最後のデプロイメントのトークンとは異なるトークンを指定します。各デプロイにタイムスタンプまたは GUID を指定して、アセットを常に再アップロードできます。

[UseRoute53Nameservers]

開発者ポータルのカスタムドメイン名を作成している場合にのみ適用されます。true を指定して、Route 53 HostedZone および RecordSet の作成をスキップします。Route 53 の代わりに独自のネームサーバーホスティングを提供する必要があります。それ以外の場合、このフィールドを false のままにします。

開発者ポータルの管理者ユーザーを作成する

開発者ポータルをデプロイした後、少なくとも 1 人の管理者ユーザーを作成します。そのためには、新しいユーザーを作成し、そのユーザーを開発者ポータルのデプロイ時に AWS CloudFormation が作成した Amazon Cognito ユーザープールの管理者グループに追加します。

管理者ユーザーを作成する

  1. 開発者ポータルで、[Register (登録)] を選択します。

  2. E メールアドレスとパスワードを入力し、[Register (登録)] を選択します。

  3. 別のウェブブラウザタブで Amazon Cognito コンソールにサインインします。

  4. [ユーザープールの管理] を選択します。

  5. 開発者ポータルのデプロイ時に設定した開発者ポータルのユーザープールを選択します。

  6. 管理者に昇格するユーザーを選択します。

  7. [Add to group (グループに追加)] を選択します。

  8. ドロップダウンメニューで、[{stackname}-dev-portalAdminsGroup] を選択します。{stackname} は開発者ポータルをデプロイしたときのスタック名です。

  9. [Add to group (グループに追加)] を選択します。

  10. 開発者ポータルで、同じ認証情報を使用してログアウトして再度ログインします。[My Dashboard (自分のダッシュボード)] の横、右上隅に [Admin Panel (管理パネル)] リンクが表示されます。

開発者ポータルのユーザーの管理

管理者ユーザーとしてサインインした後、[管理パネル] の [アカウント] セクションを使用してユーザーを管理できます。管理者ユーザーは、開発者ポータルから、新しいユーザーを招待したり、ユーザーを削除したり、既存のユーザーを管理者ステータスに昇格したりできます。

開発者ポータルに API Gateway マネージド型 API を発行する

以下の手順では、API 所有者として、開発者ポータルに API を公開して、顧客がそれをサブスクライブできるようにする方法を概説します。

ステップ 1: 公開できる API Gateway マネージド型 API を使用可能にする

  1. まだそうしていない場合は、API をステージにデプロイします。

  2. まだそうしていない場合は、使用量プランを作成し、デプロイされた API の API ステージに関連付けます。

    注記

    API キーを使用量プランに関連付ける必要はありません。開発者ポータルがこれを行います。

  3. [Developer Portal (開発者ポータル)] にサインインして、[Admin Panel (管理パネル)] に移動します。

  4. [Admin Panel (管理パネル)] API リストに API が表示されます。API リストでは、API は使用量プランごとに分類されています。[Not Subscribable No Usage Plan (サブスクライブ不可、使用量プランなし)] グループは、使用量プランに関連付けられていない API を一覧表示します。

ステップ 2: API Gateway マネージド型 API を開発者ポータルに表示する

  1. [Admin Panel (管理パネル)] API リストで、API の [Displayed (表示)] 値を確認します。最初にアップロードされたとき、この値は [False] に設定されます。

  2. 開発者ポータルで API を表示するには、[False] ボタンを選択します。その値が True に変わり、API が表示されるようになったことを示します。

    ヒント

    使用量プランのすべての API が表示されるようにするには、使用量プランのヘッダーバーで [False] または [Partial (一部)] ボタンを選択します。

  3. [API] パネルに移動して、顧客に表示される開発者ポータルを確認します。左ナビゲーション列に一覧表示された API が表示されます。

    API が使用量プランに関連付けられているステージにデプロイされている場合、API の [Subscribe (サブスクライブ)] ボタンが表示されます。このボタンをクリックすると、顧客の API キーが、その API が関連付けられている使用量プランに関連付けられます。

API Gateway マネージド型 API が表示されたので、顧客が SDK をダウンロードできるように SDK の生成を有効にできます。

ステップ 3: SDK 生成を有効にする

  1. [Admin Panel (管理パネル)] API リストで、[Disabled (無効)] ボタンを選択します。この値は [Enabled (有効)] に変わります。これは、SDK の生成が許可されることを示します。

  2. [API] パネルに移動し、左ナビゲーション列の API を選択します。[SDK のダウンロード] ボタンと [API のエクスポート] ボタンが表示されます。

API Gateway マネージド型 API の更新または削除

公開後に API Gateway で API を変更した場合は、再デプロイする必要があります。

API Gateway マネージド型 API を更新するには

  1. API Gateway コンソール、AWS CLI、または SDK で API 必要な変更を加えます。

  2. 以前と同じステージに API を再デプロイします。

  3. 開発者ポータルで、[Admin Panel (管理パネル)] API リストの [Update (更新)] を選択します。これにより、開発者ポータル UI に表示される API が更新されます。

    注記

    [Download SDK (SDK のダウンロード)] ボタンは、開発者ポータルで更新しなくても、常にデプロイされている最新バージョンの API を取得します。

  4. [API] パネルに移動し、左ナビゲーション列の API を選択します。変更が表示されます。

開発者ポータルの API リストに API を表示しないようにするには (顧客のアクセスは取り消さずに)。

  1. [Admin Panel (管理パネル)] API リストで、API の [Displayed (表示)] 値を確認します。API が表示されている場合、この値は [True] に設定されます。

  2. API が表示されないようにするには、[True] ボタンを選択します。その値が [False] に変わり、API が非表示になったことを示します。

  3. [API] パネルに移動します。左ナビゲーション列に一覧表示された API が表示されなくなります。

顧客のアクセスを完全に削除せずに API へのアクセスを取り消すには、API Gateway コンソール、API Gateway CLI、または REST API で次のいずれかを実行する必要があります。

  • 使用量プランから API キーを削除します。

  • 使用量プランから API ステージを削除します。

非 API Gateway マネージド型 API を削除するには

非 API Gateway マネージド型 API の表示を停止して、顧客のアクセスを削除するには、[Delete (削除)] を選択します。これによって API は削除されませんが、開発者ポータルから OpenAPI 仕様ファイルが削除されます。

開発者ポータルに非 API Gateway マネージド型 API を発行する

次の手順では、非 API Gateway マネージド型 (または「生成」) API を顧客に公開する方法について説明します。JSON、YAML、または YML ファイルに、OpenAPI 2.0 (Swagger) または 3.x 定義 API をアップロードできます。

開発者ポータルで非 API Gateway マネージド型 API を公開するには

  1. [Developer Portal (開発者ポータル)] にサインインして、[Admin Panel (管理パネル)] に移動します。

  2. [Generic APIs (汎用 API)] で、[Add API (API の追加)] を選択します。

  3. API 用の OpenAPI ファイルが存在するディレクトリを参照して、アップロードするファイルを選択します。

  4. [Upload] を選択します。

    注記

    解析できないファイルや API タイトルが含まれていないファイルがあると、警告が表示され、それらのファイルはアップロードされません。他のすべてのファイルがアップロードされます。ダイアログを閉じる場合は、[x] アイコンを選択する必要があります。

  5. [Generic APIs (汎用 API)] に API が一覧表示されます。表示されない場合、[Admin Panel (管理パネル)] から移動して、もう一度戻ってリストを更新します。

お客様が開発者ポータルを使用する方法

アプリケーションを構築して API をテストするには、顧客は開発者ポータルに登録して開発者アカウントを作成する必要があります。

開発者アカウントを作成して API キーを取得するには

  1. 開発者ポータルで、[Register (登録)] を選択します。

  2. E メールアドレスとパスワードを入力し、[Register (登録)] を選択します。

  3. API キーを確認するには、[My Dashboard (自分のダッシュボード)] を選択します。

開発者アカウントは、通常、API を使用およびテストするために必要な API キーを顧客に提供します。これは、ユーザーと顧客の両方の使用状況の追跡を可能にします。

お客様が最初に登録すると、新しい API キーはユーザーの API に関連付けられません。

API の API キーを有効にするには

  1. [API] を選択します。

  2. API リストから API を選択し、[Subscribe (サブスクライブ)] を選択します。

    これにより、API キーが、その API が関連付けられている使用量プランに関連付けられます。

顧客は API にサブスクライブされ、API のメソッドを呼び出すことができます。API の毎日の使用統計は、[MyDashboard] に表示されます。

顧客は、サブスクライブしなくても開発者ポータル UI で API メソッドを試すことができます。

注記

いずれかの API メソッドで API キーが必要な場合は、メソッドリストの上に [Authorize (承認)] ボタンが表示されます。API キーを必要とするメソッドを黒いロックアイコンが表示されます。API キーを必要とするメソッドを試すには、[Authorize (承認)] ボタンを選択して、API ステージの使用量プランに関連付けられている有効な API キーを入力します。

すでにサブスクライブしている API に [Authorize (承認)] ボタンが表示される場合、無視しても問題ありません。

顧客は、開発者ポータルからカスタマーフィードバックを送信できます。

お客様のフィードバックは開発者ポータルの DynamoDB テーブルに保存されます。このテーブルのデフォルト名は、[DevPortalFeedback] です。また、[DevPortalAdminEmail] フィールドで指定された E メールアドレスに E メールが送信されます。開発者ポータルがデプロイされたときに E メールアドレスが指定されていないと [ご意見をお持ちですか?] ボタンは表示されません。

注記

このテーブルの名前を変更する場合は、アカウントリージョン内で一意の名前を使用する必要があります。

[管理パネル] で API の SDK 生成を有効にしている場合、顧客は SDK をダウンロードし、API 定義をエクスポートできます。詳細については、「API Gateway で REST API の SDK を生成する」と「API Gateway から REST API をエクスポートする」を参照してください。

開発者ポータルのベストプラクティス

以下は、開発者ポータルをデプロイするときに推奨されるベストプラクティスです。

  • ほとんどの場合、すべての API に対して 1 つの開発者ポータルをデプロイするだけで済みます。場合によっては、API の開発バージョンと本稼働用バージョンに別々の開発者ポータルを選択することもできます。プロダクション API に複数の開発者ポータルを使用することはお勧めしません。

  • 使用量プランを作成してそれをステージに関連付ける場合は、API キーを使用量プランに関連付ける必要はありません。開発者ポータルがこれを行います。

  • 特定の使用量プランの API が表示されている場合は、その使用量プランのすべての API をサブスクライブすることができます (顧客に表示されていない場合も)。