サーバーレス開発者ポータルを使用して 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 を API Gateway から直接公開できます。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 を使用します。[Deploy (デプロイ)] ボタンを選択して、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 コンソールで、[Application settings (アプリケーションの設定)] で必要な開発者ポータルスタックパラメータを入力します。

    注記

    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 SAM CLI がインストールされ、設定されていることを確認します。

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

  3. zip 形式の 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 をサブスクライブすることができます (顧客に表示されていない場合も)。