API の試用

SmartDocs API リファレンス ドキュメントを閲覧するだけでなく、開発者は [この API を試す] パネルを使用できます。つまり、API ドキュメントを見ながらの API 操作が可能です。ポータルの中で、API にリクエストを送信して、そのレスポンスを見ることができます。API をポータルで試すことにより、API ユーザーは、API を使って自分のコードを動作させるために何をする必要かあるかを理解できます。

API に API キーまたは認証が必要な場合は、ユーザーが API を操作できるようにポータルを構成する必要があります。このページでは、デベロッパーが [この API を試す] を使用できるようにするために必要な要件と設定について説明します。また、それぞれのタスクを実行するために最低限必要な Identity and Access Management のロールについても説明します。IAM の権限について詳しくは、以下をご覧ください。

前提条件

  • API バックエンドをデプロイしておく必要があります。
  • API に API キーが必要な場合は、API キーによる API アクセスの制限の説明に従って OpenAPI ドキュメントを構成する必要があります。
  • API に認証が必要な場合は、選択した認証方法で OpenAPI ドキュメントを構成する必要があります。認証方法の選択をご覧ください。

  • API は DNS 経由でアクセスできるようになっていなければなりません。

    • API を App Engine フレキシブル環境にデプロイした場合、YOUR_PROJECT_ID.appspot.com 形式の名前を持つ DNS エントリが自動的に作成されます。前の例で、YOUR_PROJECT_ID は API をデプロイした Google Cloud プロジェクトの ID です。つまり、追加構成なしでポータルで API をテストできます。
    • 他のバックエンド（Compute Engine や GKE など）の場合、API がカスタム ドメイン名（たとえば、myapi.mycompany.com）を使用するように構成されていなければ、API を cloud.goog ドメインを使用するように構成する必要があります。

API Explorer 設定の構成

API で API キーや Firebase 認証または Auth0 認証が必要な場合、ユーザーが API を試用できるようにするには、次の設定を構成する必要があります。このセクションでは、API キーと認証設定の構成方法について説明します。

API キーを構成する

ポータルで API キーを構成するには:

  1. Google Cloud Console で、[API とサービス] の [認証情報] に移動します。

    [ドメインの確認] ページに移動

  2. Google Cloud コンソール ウィンドウ上部にある [プロジェクト] プルダウン リストで、API を作成した Google Cloud プロジェクトを選択します。

    • 既存の API キーを使用する場合:

      1. 使用する API キーの横にある [API キーを編集] をクリックします。
      2. API キーの右にある [コピー] をクリックして、API キーをクリップボードにコピーします。
      3. [キャンセル] をクリックします。

    • API キーを作成する必要がある場合:

      1. [認証情報を作成] をクリックして [API キー] を選択します。
      2. キーをクリップボードにコピーします。
      3. [閉じる] をクリックします。

  3. ポータルに戻ります。

  4. [設定] をクリックします。

  5. [API] タブをクリックし、プルダウン リストから API を選択します。

  6. [APIs Explorer Settings] セクションで、API キーを [Google API key] フィールドに貼り付けます。

  7. [Save] をクリックします。

Firebase を構成する

Firebase を構成するには:

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

    • 既存の Firebase プロジェクトがない場合:

      1. [プロジェクトを追加] をクリックし、API が含まれている Google Cloud プロジェクト名を選択します。
      2. [Authentication] カードで [始める] をクリックします。
      3. [ログイン方法] タブをクリックします。
      4. [ログイン プロバイダ] セクションで、使用するプロバイダを有効にします。
      5. [承認済みドメイン] セクションで [ドメインの追加] をクリックして、ポータル ドメイン名（endpointsportal.example-api.example.com など）を追加します。
      6. [ウェブ設定] をクリックします。カスタマイズされたコード スニペットが表示されます。次の手順でコード スニペットの情報が必要となるので、Firebase コンソールは開いたままにしておきます。

    • 既存の Firebase プロジェクトがある場合:

      1. [開発] > [Authentication] に移動します。
      2. [ログイン方法] タブをクリックします。
      3. [承認済みドメイン] セクションで [ドメインの追加] をクリックして、ポータル ドメイン名（endpointsportal.example-api.example.com など）を追加します。
      4. [ウェブ設定] をクリックします。カスタマイズされたコード スニペットが表示されます。次の手順でコード スニペットの情報が必要となるので、Firebase コンソールは開いたままにしておきます。

  2. ブラウザで別のタブを開き、ポータルに移動します。

  3. [設定] をクリックします。

  4. [設定] ページで [API] タブをクリックし、プルダウン リストから API を選択します。

  5. [APIs Explorer Settings] セクションで、次の操作を行います。

    1. Firebase コード スニペットから apiKey フィールドの値をコピーし、[Google API key] フィールドに貼り付けます。
    2. Firebase コード スニペットから authDomain フィールドの値をコピーし、[Firebase auth domain] フィールドに貼り付けます。

  6. [保存] をクリックします。

詳細については、Firebase のドキュメントをご覧ください。

Auth0 の構成

タスクの概要を示す次のリストに従って、Auth0 とポータルを構成します。

タスク 1.Cloud Endpoints サービス用の Auth0 API があることを確認します。

タスク 2.Auth0 アプリケーション設定を構成します。

タスク 3.ポータルで Auth0 設定を構成します。

タスク 1: Endpoints サービス用の Auth0 API があることを確認する

  1. Auth0 ダッシュボードにログインします。

  2. 左側のナビゲーション バーで [APIs] をクリックします。[API Audience] の形式が https://SERVICE_NAME（SERVICE_NAME は自分の Endpoints サービスの名前）となっている場合、API がすでに作成済みです。次のタスクに進んで、Auth0 アプリケーション設定を構成してください。

    それ以外の場合は、次のように API を作成します。

    1. [+ Create API] をクリックします。
    2. 名前を入力します。

    3. [Identifier] フィールドに、https://SERVICE_NAME の形式で URL を入力します。

      SERVICE_NAME は、Endpoints サービスの名前に置き換えます。サービス名がわからない場合は、サービス名と構成 ID の取得を参照して Endpoints サービスの名前を確認してください。

    4. [Create] をクリックします。

タスク 2: Auth0 アプリケーション設定を構成する

  1. Auth0 ダッシュボードで、左側のナビゲーション バーにある [Applications] をクリックします。
  2. 既存の Auth0 アプリケーションを選択するか、[+ Create Application] をクリックして新規に作成します。

  3. アプリケーションの [Settings] タブを開いて下にスクロールし、[Allowed Callback URLs] フィールドにポータルの OAuth リダイレクト URL を追加します。ポータルの OAuth リダイレクト URL はポータルの URL と /oauth/redirect です（たとえば、https://endpointsportal.example-api.example.com/oauth/redirect）。

    [Allowed Callback URLs] フィールドには複数の URL をカンマで区切って指定できます。入力した URL の末尾に / 文字を含めないでください。

  4. [Save Changes] をクリックします。

    Auth0 の [Settings] ブラウザタブを開いたままにしておきます。次の手順でこのタブの情報が必要となります。

タスク 3: ポータルで Auth0 設定を構成する

  1. ブラウザで別のタブを開き、ポータルに移動します。
  2. [設定] をクリックします。
  3. [設定] ページで [API] タブをクリックし、プルダウン リストから API を選択します。

  4. [APIs Explorer Settings] セクションで、次の操作を行います。

    1. Auth0 ダッシュボードの [Client ID] フィールドの値をコピーし、[Auth0 client ID] フィールドに貼り付けます。
    2. Auth0 ダッシュボードの [Domain] フィールドの値をコピーし、[Auth0 domain] フィールドに貼り付けます。

  5. [Save] をクリックします。

Auth0 を構成する方法については、Auth0 ドキュメントの Auth0 ダッシュボードの概要をご覧ください。