API の公開

このページの内容は ApigeeApigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

ここでは、API をポータルに公開してアプリ デベロッパーが API を利用できるようにする方法について説明します。

API 公開の概要

API をポータルに公開する方法は、次の 2 段階のプロセスから成ります。

  1. ポータルに公開する API プロダクトを選択する。
  2. OpenAPI ドキュメントまたは GraphQL スキーマから API リファレンス ドキュメントをレンダリングし、アプリ デベロッパーが API を理解できるようにする(詳細については、API ドキュメントについてをご覧ください)。

ポータルに公開される内容

API を公開すると、ポータルに対して以下の更新が自動で行われます。

  • API リファレンス ドキュメント。API の公開に OpenAPI ドキュメントと GraphQL スキーマのどちらを使用するかによって、表示されるインターフェースが変わります。詳しくは、以下をご覧ください。
  • API リファレンス ページへのリンクが [API] ページに追加される

    [API] ページ(サンプル ポータルに含まれる)には、ポータルに公開されたすべての API がアルファベット順に一覧表示され、詳細についてはそれぞれの API リファレンス ドキュメントへのリンクが記載されます。必要に応じて、次のものをカスタマイズできます。

    • 各 API カードに表示される画像
    • デベロッパーが [API] ページで関連 API を見つけられるように、API のタグ付けに使用されるカテゴリ
    2 つのカテゴリと画像の使用を示すライブポータルの [API] ページ 2 つのカテゴリと画像の使用を示すライブポータルの [API] ページ

SmartDocs(OpenAPI)

OpenAPI ドキュメントを使用して API を公開すると、SmartDocs API リファレンス ドキュメントがポータルに追加されます。

デベロッパーは SmartDocs API リファレンス ドキュメントを確認し、[この API を試す] パネルを使用して API リクエストを行い出力を表示できます。[この API を試す] は、OpenAPI ドキュメントで定義されたセキュリティ方式に基づいて、基本認証、API キー認証、または OAuth 認証を使用し、保護されていないエンドポイントや保護されたエンドポイントで動作します。OAuth では、認証コード、パスワード、およびクライアント認証情報のフローがサポートされています。

API 呼び出しの承認、[この API を試す] パネルの固定解除、関連する仕様のダウンロード、API の実行方法を示すコールアウトを含む API リファレンス ドキュメント ページ。

API 呼び出しの承認、[この API を試す] パネルの固定解除、関連する仕様のダウンロード、API の実行方法を示すコールアウトを含む API リファレンス ドキュメント ページ。

[ 全画面表示] をクリックすると [この API を試す] パネルが開きます。開いたパネルでは、以下に示すように、curl の呼び出しとコードサンプルをさまざまな形式(HTTP、Python、Node.js など)で表示できます。

開いた [この API を試す] パネル

開いた [この API を試す] パネル

GraphQL エクスプローラ

GraphQL スキーマを使用して API を公開すると、GraphQL エクスプローラがポータルに追加されます。GraphQL エクスプローラは、API に対してクエリを実行するためのインタラクティブなツールです。このエクスプローラは、GraphQL Foundation が開発した GraphQL IDE のリファレンス実装である GraphiQL をベースにしています。

デベロッパーは GraphQL エクスプローラを使用して、スキーマベースのインタラクティブなドキュメントの閲覧、クエリの作成と実行、クエリ結果の表示、スキーマのダウンロードを行えます。API へのアクセスを保護するために、デベロッパーは [リクエスト ヘッダー] ペインで承認ヘッダーを渡すことができます。GraphQL の詳細については、graphql.org をご覧ください。

ポータルの GraphQL エクスプローラ

ポータルの GraphQL エクスプローラ

API ドキュメントについて

各 OpenAPI ドキュメントや GraphQL ドキュメントは、API のライフサイクル全体を通して信頼できる情報源として機能します。開発から公開、モニタリングまで、API ライフサイクルの各フェーズで同じドキュメントが使用されます。ドキュメントを変更する場合は、その変更が他のライフサイクル フェーズを通して API に与える影響を認識する必要があります。詳細については、ドキュメントを変更するとどうなるかをご覧ください。

API をポータルに公開するとき、API リファレンス ドキュメントをレンダリングする OpenAPI ドキュメントまたは GraphQL ドキュメントのバージョンを保存します。ドキュメントを変更する場合は、ポータルに公開されている API リファレンス ドキュメントを更新して、最新の変更を反映できます。

コールバック URL について

OAuth 2.0 認証コード権限付与タイプ(「3-legged OAuth」と呼ばれることもあります)を使用するときなど、アプリにコールバック URL が必要な場合は、デベロッパーがアプリを登録する際にコールバック URL の指定を求めることができます。通常、このコールバック URL では、クライアント アプリに代わって認証コードを受け取るアプリの URL を指定します。詳細については、認証コード権限付与タイプを実装するをご覧ください。

アプリの登録時にコールバック URL を要求するかどうかは、ポータルへ API を追加するときに構成できます。この設定はいつでも変更できます。詳細は、API のコールバック URL を管理するをご覧ください。

アプリを登録する際、デベロッパーは、コールバック URL を必要とするすべての API に対してコールバック URL を入力する必要があります。詳細は、アプリの登録をご覧ください。

[この API を試す] パネルをサポートするように API プロキシを構成する

OpenAPI ドキュメントを使用して API を公開する前に、次のように、SmartDocs API リファレンス ドキュメントの [この API を試す] パネルでリクエストを API プロキシがサポートするように構成する必要があります。

  • API プロキシに CORS サポートを追加して、クライアント側のクロスオリジン リクエストを強制します。
    CORS は、ウェブページで実行される JavaScript XMLHttpRequest(XHR)呼び出しがオリジンではないドメインのリソースとやり取りできるようにする標準の仕組みです。CORS は、すべてのブラウザに組み込まれている同一オリジン ポリシーに対する一般的な解決策です。
  • API プロキシ構成を更新します(基本認証または OAuth 2.0 を使用している場合)。

次の表では、認証方式別に、SmartDocs API リファレンス ドキュメントの [この API を試す] パネルをサポートするための API プロキシの構成要件を示します。

認証方式 ポリシーの構成要件
なし、または API キー API プロキシへの CORS サポートの追加で説明されている手順に沿って、API プロキシに CORS サポートを追加します。
基本認証 次の手順を行います。
  1. API プロキシへの CORS サポートの追加の説明に従って、API プロキシに CORS サポートを追加します。
  2. Add CORS ポリシーで、Access-Control-Allow-Headers ヘッダーに authorization 属性が含まれていることを確認します。次に例を示します。
    <Header name="Access-Control-Allow-Headers">
      origin, x-requested-with, accept, content-type, authorization
    </Header>
OAuth 2.0
  1. API プロキシへの CORS サポートの追加の説明に従って、API プロキシに CORS サポートを追加します。
  2. Add CORS ポリシーで、Access-Control-Allow-Headers ヘッダーに authorization 属性が含まれていることを確認します。次に例を示します。
    <Header name="Access-Control-Allow-Headers">
      origin, x-requested-with, accept, content-type, authorization
    </Header>
  3. OAuth 2.0 ポリシーの RFC に準拠していない動作を修正します。簡単にするため、GitHub にあるサンプル OAuth 2.0 ソリューションを使用するか、次の操作を行います。
    • OAuth 2.0 ポリシーの <GrantType> 要素が request.formparam.grant_type(フォーム パラメータ)に設定されるようにします。詳細については、<GrantType> をご覧ください。
    • OAuth 2.0 ポリシーの token_type がデフォルトの BearerToken ではなく Bearer に設定されるようにします。

API を管理する

次のセクションで説明するように、API を管理します。

API を探索する

ポータルにある API を表示するには、コンソールまたは curl コマンドを使用します。

コンソール

API カタログを表示するには:

  1. [公開] > [ポータル] を選択し、目的のポータルを選択します。
  2. ポータルのホームページで、[API catalog] をクリックします。
    または、上部のナビゲーション バーにあるポータル プルダウン メニューから [API catalog] を選択します。
    API カタログの [API] タブに、ポータルに追加された API のリストが表示されます。

    名前、説明、公開設定、カテゴリ、関連仕様、変更など、API に関する情報を表示する [API] タブ

    名前、説明、公開設定、カテゴリ、関連仕様、変更など、API に関する情報を表示する [API] タブ

    上の図でハイライト表示されているように、[API] タブでは次のことができます。

curl

organizations.sites.apidocs/list を使用して API を一覧表示するには:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal

レスポンス ペイロードでページ分割を使用する手順については、ページネーションに関する注をご覧ください。

レスポンス ペイロード:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

ここで

  • modified: カタログ アイテムが最後に変更された時刻(エポックからのミリ秒数)。例: 1698165480000
  • id: カタログ アイテムの ID。例: 399668

ページネーションに関する注:

  • ページサイズ: pageSize を使用して、1 ページで返されるリストアイテムの数を指定します。デフォルトは 25、最大値は 100 です。追加のページがある場合は、nextPageToken にトークンが挿入されます。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    次のように置き換えます。

    • PAGE_SIZE は、1 ページで返すリストアイテムの数に置き換えます。例: 10

    レスポンス ペイロード:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "requestId": "918815495",
      "data": [
        {
          "siteId": "my-org-myportal",
          "title": "Hello New World",
          "description": "Simple hello new world example",
          "specId": "apigee",
          "modified": "1699146887000",
          "anonAllowed": true,
          "imageUrl": "/files/camper1.jpg?v=1695841491415",
          "id": "381054",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello New World"
        }
      ],
      "nextPageToken": "7zcqrin9l6xhi4nbrb9"
    }
    
  • ページトークン:

    複数ある場合は、pageToken を使用して後続のページを取得します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
          -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    次のように置き換えます。

    • PAGE_SIZE は、1 ページで返すリストアイテムの数に置き換えます。例: 10
    • PAGE_TOKEN は値 nextPageToken で置き換えます。例: 7zcqrin9l6xhi4nbrb9

API を追加する

API をポータルに追加するには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. [追加] をクリックします。

    [Add an API product to the catalog] ダイアログが表示されます。

  4. ポータルに追加する API プロダクトを選択します。

  5. [次へ] をクリックします。API の詳細ページが表示されます。

  6. API リファレンス ドキュメントの内容と、ポータル上での公開設定を構成します。

    フィールド 説明
    公開済み API をポータルに公開するには、[公開済み] をオンにします。API を公開する準備ができていない場合は、チェックボックスをオフにします。この設定は、API を公開または公開停止するの説明に従って後で変更できます。
    タイトルを表示 カタログに表示される API のタイトルを更新します。デフォルトでは、API プロダクト名が使用されます。表示タイトルは後で変更できます。詳細は、表示タイトルと説明を編集するをご覧ください。
    Display description カタログに表示される API の説明を更新します。デフォルトでは、API プロダクトの説明が使用されます。表示の説明は後で変更できます。詳細は、表示タイトルと説明を編集するをご覧ください。
    デベロッパーによるコールバック URL の指定が必要 アプリ デベロッパーがコールバック URL を指定する必要があるようにする場合はオンにします。コールバック URL は後で追加または更新できます。詳細は、API のコールバック URL を管理するをご覧ください。
    API ドキュメント

    OpenAPI ドキュメントを使用するには:

    1. [OpenAPI document] を選択します。
    2. [Select Document] をクリックします。
    3. 次のいずれかを行います。
      • [ファイルをアップロード] タブをクリックし、ファイルをアップロードします。
      • [Import from a URL] タブをクリックし、インポート元の名前と URL を指定して仕様をインポートします。
    4. [選択] をクリックします。

    GraphQL スキーマを使用するには:

    1. [GraphQL Schema] を選択します。
    2. [ドキュメントを選択] をクリックします。
    3. GraphQL スキーマに移動して選択します。
    4. [選択] をクリックします。

    または、[No documentation] を選択して、API の追加後にドキュメントを追加することもできます。詳細については、API ドキュメントを管理するをご覧ください。

    視覚補助

    オーディエンス管理機能のベータ版リリースに登録していない場合は、次のいずれかのオプションを選択します。

    • Anonymous users: すべてのユーザーに API の閲覧を許可します。
    • Registered users: 登録ユーザーのみに API の閲覧を許可します。

    オーディエンス管理機能のベータ版リリースに登録している場合は、次のいずれかを選択します。

    • Public (visible to anyone): すべてのユーザーに API の閲覧を許可します。
    • Authenticated users: 登録ユーザーのみに API の閲覧を許可します。
    • Selected audiences: API の閲覧を許可する特定のオーディエンスを選択します。

    オーディエンスの公開設定は、後で管理できます。API の公開設定を管理するをご覧ください。

    表示画像 [API] ページの API カードに画像を表示するには、[画像を選択] をクリックします。[画像を選択] ダイアログで、既存の画像を選択するか、新しい画像をアップロードするか、外部画像の URL を指定して [選択] をクリックします。API サムネイルをプレビューし、[選択] をクリックします。画像は、API カードの画像を管理するの手順に沿って後で追加できます。外部画像の URL を指定しても、その画像はアセットにアップロードされません。また、統合ポータルで画像を読み込むには、その画像が利用可能である必要があります。画像の利用は、コンテンツ セキュリティ ポリシーによってブロックまたは制限される場合があります。
    カテゴリ

    アプリ デベロッパーが API ページで関連 API を見つけられるよう、API にタグ付けするカテゴリを追加します。カテゴリを特定するには:

    • プルダウン リストからカテゴリを選択します。
    • 新しいカテゴリを追加するには、カテゴリ名を入力して Enter を押します。新しいカテゴリは [カテゴリ] ページに追加され、他の API を追加または編集する際に使用できるようになります。

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

curl

organizations.sites.apidocs.create を使用して API をポータルに追加するには:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • TITLE は、表示タイトルに置き換えます。例: Hello World 2
  • DESCRIPTION は、表示の説明に置き換えます。例: Simple hello world example
  • ANON_TRUE_OR_FALSE は、true または false(デフォルト)に置き換えます。true は匿名ユーザー アクセスを有効にします。オーディエンス管理機能のベータ版リリースに登録している場合、この設定は無視されます。
  • IMAGE_URL は、カタログ アイテムに使用される外部画像の URL またはポータルに保存されている画像ファイルのファイルパス(例: /files/book-tree.jpg)に置き換えます。外部画像の URL を指定しても、その画像はアセットにアップロードされません。また、統合ポータルで画像を読み込むには、その画像が利用可能である必要があります。画像の利用は、コンテンツ セキュリティ ポリシーによってブロックまたは制限される場合があります。
  • CALLBACK_TRUE_OR_FALSE は、true または false(デフォルト)に置き換えます。true の場合、アプリを管理するときにポータル ユーザーが URL を入力する必要があります。
  • CATEGORY_ID は、カテゴリの ID に置き換えます。例: bf6505eb-2a0f-47af-a00a-ded40ac72960。複数のカテゴリ ID はカンマで区切ります。list API categories コマンドを使用して、カテゴリ ID を取得します。

  • PUBLISHED_TRUE_OR_FALSE は、true または false(デフォルト)に置き換えます。true は、API が一般公開されていることを示します。

  • API_PRODUCT は、API プロダクトの名前に置き換えます。例: Hello World 2

レスポンス ペイロード:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

ここで

  • modified: カタログ アイテムが最後に変更された時刻(エポックからのミリ秒数)。例: 1698165480000
  • id: カタログ アイテムの ID。例: 399668

API を編集する

API を追加したら、コンソールまたは API 呼び出しを使用して編集を行います。

このセクションでは、ポータルの既存の API を変更する手順の例を示します。

具体的な変更設定については、以降のセクションをご覧ください。

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [API details] で変更を行います。オプションの詳細については、API を追加するをご覧ください。
  6. [保存] をクリックします。

curl

API を追加したら、organizations.sites.apidocs.update 呼び出しを使用して編集を行います。

この例では、ポータルの API の公開ステータスを true から false に変更するために必要な手順を説明します。必要に応じて、1 回の API 呼び出しで複数の設定を変更できます。

  1. 各 API を一意に識別できる id を見つけるため、organizations.sites.apidocs/list を使用してポータルの API のリストを取得します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    次のように置き換えます。

    • ORG_NAME は、組織の名前に置き換えます。例: my-org
    • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal

    レスポンス ペイロード:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "requestId": "1167960478",
      "data": [
        {
          "siteId": "my-org-myportal",
          "title": "Hello New World",
          "description": "Simple hello new world example",
          "specId": "hellowworld",
          "modified": "1695841621000",
          "anonAllowed": true,
          "imageUrl": "/files/camper1.jpg?v=1695841491415",
          "id": "381054",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello New World"
        },
        {
          "siteId": "my-org-myportal",
          "title": "mock-product",
          "description": "Mock product",
          "specId": "apigee spec",
          "modified": "1698956849000",
          "anonAllowed": true,
          "id": "399638",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
          ],
          "published": true,
          "apiProductName": "mock-product"
        },
        {
          "siteId": "my-org-myportal",
          "title": "Hello World 2",
          "description": "Simple hello world example",
          "specId": "hello-new-world",
          "modified": "1698950207000",
          "anonAllowed": true,
          "imageUrl": "/files/book-tree.jpg?v=1698165437881",
          "id": "399668",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello World 2"
        }
      ]
    }

    ここで

    • modified: カタログ アイテムが最後に変更された時刻(エポックからのミリ秒数)。例: 1698165480000
    • id: カタログ アイテムの ID。例: 399668
  2. organizations.sites.apidocs.get 呼び出しを使用して、特定の API の現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    次のように置き換えます。

    • ORG_NAME は、組織の名前に置き換えます。例: my-org
    • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
    • API_DOC は、生成されたドキュメントの id に置き換えます。例: 399668。この値を確認するには、list API docs コマンドを使用します。

    レスポンス ペイロード:

    {
      "status": "success",
      "message": "apidoc returned",
      "requestId": "2072952505",
      "data": {
        "siteId": "my-org-myportal",
        "title": "Hello World 2",
        "description": "Simple hello world example",
        "specId": "hello-new-world",
        "modified": "1698950207000",
        "anonAllowed": true,
        "imageUrl": "/files/book-tree.jpg?v=1698165437881",
        "id": "399668",
        "categoryIds": [
          "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
          "61c1014c-89c9-40e6-be3c-69cca3505620"
        ],
        "published": true,
        "apiProductName": "Hello World 2"
      }
    }
  3. 変更しない値を organizations.sites.apidocs.update 呼び出しに指定し、残りの値を変更します。行を省略すると、デフォルト設定が使用されます。この例では、published 設定を true から false に変更します。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": false,
            "apiProductName": "API_PRODUCT",
         }'
    

    次のように置き換えます。

    • TITLE は、表示タイトルに置き換えます。例: Hello World 2
    • DESCRIPTION は、表示の説明に置き換えます。例: Simple hello world example
    • ANON_TRUE_OR_FALSE は、true または false(デフォルト)に置き換えます。true は匿名ユーザー アクセスを有効にします。オーディエンス管理機能のベータ版リリースに登録している場合、この設定は無視されます。
    • IMAGE_URL は、カタログ アイテムに使用される外部画像の URL またはポータルに保存されている画像ファイルのファイルパス(例: /files/book-tree.jpg)に置き換えます。外部画像の URL を指定しても、その画像はアセットにアップロードされません。また、統合ポータルで画像を読み込むには、その画像が利用可能である必要があります。画像の利用は、コンテンツ セキュリティ ポリシーによってブロックまたは制限される場合があります。
    • CALLBACK_TRUE_OR_FALSE は、true または false(デフォルト)に置き換えます。true の場合、アプリを管理するときにポータル ユーザーが URL を入力する必要があります。
    • CATEGORY_ID は、カテゴリの ID に置き換えます。例: bf6505eb-2a0f-47af-a00a-ded40ac72960。複数のカテゴリ ID はカンマで区切ります。list API categories コマンドを使用して、カテゴリ ID を取得します。
    • API_PRODUCT は、API プロダクトの名前に置き換えます。例: Hello World 2

    レスポンス ペイロード:

    {
      "status": "success",
      "message": "ApiDoc updated",
      "requestId": "197181831",
      "data": {
        "siteId": "my-org-myportal",
        "title": "Hello World 2",
        "description": "Simple hello world example.",
        "modified": "1698884328000",
        "anonAllowed": true,
        "imageUrl": "/files/book-tree.jpg",
        "id": "408567",
        "requireCallbackUrl": true,
        "categoryIds": [
          "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
          "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "Hello World 2"
      }
    }
    

API を公開または公開停止する

公開とは、アプリ デベロッパーが API を使用できるようにするプロセスです。

ポータルで API を公開または公開を停止にするには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [API detail] で、[Published (listed in the catalog)] をオンまたはオフにして、ポータルでの API の公開 / 非公開を選択します。
  6. [保存] をクリックします。

curl

update 呼び出しに次のいずれかを含めます。

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

API を編集するには:

  1. organizations.sites.apidocs.get 呼び出しを使用して、現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)"
    
  2. organizations.sites.apidocs.update 呼び出しを使用して API を編集します。変更しない値を指定し、残りの値を変更します。変更可能な設定を省略すると、デフォルト値が使用されます。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

返されるステップ、変数、ペイロードの詳細な例については、API を編集するをご覧ください。

API の公開設定を管理する

次の対象にアクセスを許可することで、ポータル内の API の公開設定を管理します。

ポータル内の API の公開設定を管理するには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. 公開設定を選択します。オーディエンス機能のベータ版リリースに登録している場合は、[API visibility] で次のいずれかのオプションを選択します。

    • Public(visible to anyone): すべてのユーザーにページの閲覧を許可します。
    • Authenticated users: 登録ユーザーのみにページの閲覧を許可します。
    • Selected audiences: ページの閲覧を許可するオーディエンスを選択します。ポータルのオーディエンスの管理をご覧ください。

    それ以外の場合は、[対象] で次のいずれかのオプションを選択します。

    • Anonymous users: すべてのユーザーにページの閲覧を許可します。
    • Registered users: 登録ユーザーのみにページの閲覧を許可します。
  6. [送信] をクリックします。

curl

オーディエンス管理機能のベータ版リリースに登録している場合は、コンソールを使用してオーディエンスを管理します。

オーディエンス管理機能に登録していない場合、公開設定は anonAllowed を使用して管理されます。

update 呼び出しに次のいずれかを含めます。

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

API を編集するには:

  1. organizations.sites.apidocs.get 呼び出しを使用して、現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)"
    
  2. organizations.sites.apidocs.update 呼び出しを使用して API を編集します。変更しない値を指定し、残りの値を変更します。変更可能な設定を省略すると、デフォルト値が使用されます。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

返されるステップ、変数、ペイロードの詳細な例については、API を編集するをご覧ください。

API のコールバック URL を管理する

API のコールバック URL を管理します。コールバック URL についてをご覧ください。

API のコールバック URL を管理するには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [API details] で、[Require developers to specify a callback URL] をオンまたはオフにして、コールバック URL が必須かどうかを指定します。
  6. [保存] をクリックします。

curl

update 呼び出しに次のいずれかを含めます。

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

API を編集するには:

  1. organizations.sites.apidocs.get 呼び出しを使用して、現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)"
    
  2. organizations.sites.apidocs.update 呼び出しを使用して API を編集します。変更しない値を指定し、残りの値を変更します。変更可能な設定を省略すると、デフォルト値が使用されます。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

返されるステップ、変数、ペイロードの詳細な例については、API を編集するをご覧ください。

API カードの画像を管理する

現在の画像を追加または変更することで、[API] ページで API カードとともに表示される画像を管理します。

API カードの画像を管理するには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [API details] で、次の操作を行います。

    • 画像が選択されていない場合は、[画像を選択] をクリックして画像を指定します。
    • [画像を変更] をクリックして、別の画像を指定します。
    • 削除するには、画像の [x] をクリックします。

    画像を指定する場合は、カタログ アイテムに使用される外部 URL を含む画像、またはポータルに保存されている画像ファイルのファイルパス(/files/book-tree.jpg など)を指定します。外部画像の URL を指定しても、その画像はアセットにアップロードされません。また、統合ポータルで画像を読み込むには、その画像が利用可能である必要があります。画像の利用は、コンテンツ セキュリティ ポリシーによってブロックまたは制限される場合があります。

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

curl

update 呼び出しに以下を含めます。

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

API を編集するには:

  1. organizations.sites.apidocs.get 呼び出しを使用して、現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)"
    
  2. organizations.sites.apidocs.update 呼び出しを使用して API を編集します。変更しない値を指定し、残りの値を変更します。変更可能な設定を省略すると、デフォルト値が使用されます。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

返されるステップ、変数、ペイロードの詳細な例については、API を編集するをご覧ください。

API にカテゴリのタグを付ける

カテゴリを使用すると、アプリ デベロッパーが関連 API を見つけやすくなります。カテゴリを管理するもご覧ください。

API にカテゴリのタグを付けるには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [カテゴリ] フィールド内をクリックし、次のいずれかの操作を行います。

    • プルダウン リストからカテゴリを選択します。
    • 新しいカテゴリを追加するには、カテゴリ名を入力して Enter を押します。新しいカテゴリは [カテゴリ] ページに追加され、他の API を追加または編集する際に使用できるようになります。
  6. API にさらに多くのカテゴリタグを付けるには、この手順を繰り返します。

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

curl

update 呼び出しに以下を含めます。

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

list categories コマンドを使用して、カテゴリ ID 番号を取得します。

API を編集するには:

  1. organizations.sites.apidocs.get 呼び出しを使用して、現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)"
    
  2. organizations.sites.apidocs.update 呼び出しを使用して API を編集します。変更しない値を指定し、残りの値を変更します。変更可能な設定を省略すると、デフォルト値が使用されます。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

返されるステップ、変数、ペイロードの詳細な例については、API を編集するをご覧ください。

表示タイトルと説明を編集する

表示タイトルと説明を編集するには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [Display title] と [Display description] を必要に応じて編集します。
  6. [保存] をクリックします。

curl

update 呼び出しに以下を含めます。

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

API を編集するには:

  1. organizations.sites.apidocs.get 呼び出しを使用して、現在の値を返します。

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)"
    
  2. organizations.sites.apidocs.update 呼び出しを使用して API を編集します。変更しない値を指定し、残りの値を変更します。変更可能な設定を省略すると、デフォルト値が使用されます。

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

返されるステップ、変数、ペイロードの詳細な例については、API を編集するをご覧ください。

API を削除する

ポータルから API を削除するには:

コンソール

  1. API カタログにアクセスします
  2. [API] が選択されていない場合は選択します。
  3. リスト内の API にカーソルを合わせて、操作メニューを表示します。
  4. [削除] をクリックします。

curl

organizations.sites.apidocs.delete を使用してポータルから API を削除するには:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • API_DOC は、生成されたドキュメントの id に置き換えます。例: 399668。この値を確認するには、list API docs コマンドを使用します。

レスポンス ペイロード:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

API ドキュメントを管理する

以降のセクションでは、API ドキュメントを更新、ダウンロード、削除する方法について説明します。

API ドキュメントを更新する

API を公開した後、いつでも新しいバージョンの OpenAPI ドキュメントまたは GraphQL ドキュメントをアップロードできます。

別のバージョンの API ドキュメントをアップロードするには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [API documentation] ペインで、次のいずれかを選択します。
    • OpenAPI document
    • GraphQL Schema
  6. [Select Document] をクリックして、ドキュメントの最新バージョンを選択します。
  7. GraphQL の場合は、エンドポイント URL を指定します。
  8. [保存] をクリックします。

curl

organizations.sites.apidocs.updateDocumentation を使用して OpenAPI または GraphQL ドキュメントのコンテンツを更新するには:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • API_DOC は、生成されたドキュメントの id に置き換えます。例: 399668。この値を確認するには、list API docs コマンドを使用します。
  • DISPLAY_NAME は、API ドキュメントの表示名に置き換えます。例: Hello World 2
  • CONTENTS は、API ドキュメントのコンテンツの Base64 エンコード文字列に置き換えます。ほとんどの開発環境には base64 変換ユーティリティが含まれています。また、多くのオンライン変換ツールが用意されています。

レスポンス ペイロード:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • API_DOC は、生成されたドキュメントの id に置き換えます。例: 399668。この値を確認するには、list API docs コマンドを使用します。
  • DISPLAY_NAME は、API ドキュメントの表示名に置き換えます。例: Hello World 2
  • ENDPOINT_URI は、エンドポイント URI のドメイン名に置き換えます。たとえば、https://demo.google.com/graphql のようになります。
  • CONTENTS は、API ドキュメントのコンテンツの Base64 エンコード文字列に置き換えます。ほとんどの開発環境には base64 変換ユーティリティが含まれています。また、多くのオンライン変換ツールが用意されています。

レスポンス ペイロード:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

API リファレンス ドキュメントがドキュメントからレンダリングされ、ライブポータルの API ページに追加されます。

API ドキュメントをダウンロードする

API を公開した後、ポータルで公開されている OpenAPI または GraphQL のリファレンス ドキュメントをいつでもダウンロードできます。

organizations.sites.apidocs.getDocumentation を使用して API ドキュメントをダウンロードするには:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • API_DOC は、生成されたドキュメントの id に置き換えます。例: 399668。この値を確認するには、list API docs コマンドを使用します。

    レスポンス ペイロード:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

ここで

contents:: API ドキュメントのコンテンツの Base64 エンコード文字列。

API ドキュメントを削除する

API ドキュメントを削除するには:

コンソール

  1. API カタログにアクセスします
  2. [API] タブをクリックします(選択されていない場合)。
  3. 編集する API の行をクリックします。
  4. [ 編集] をクリックします。
  5. [API documentation] ペインで、[No documentation] を選択します。
  6. [保存] をクリックします。

curl

API を使用して API ドキュメントのコンテンツを削除するには、空のリクエスト本文を送信して既存の設定をクリアします。

organizations.sites.apidocs.updateDocumentation を使用して空のリクエストの本文を送信し、既存のコンテンツをクリアするには:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • API_DOC は、生成されたドキュメントの id に置き換えます。例: 399668。この値を確認するには、list API docs コマンドを使用します。

レスポンス ペイロード:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

カテゴリを管理する

API にカテゴリのタグを付けることにより、アプリ デベロッパーはライブポータルの [API] ページで関連 API を見つけることができます。以下のセクションでは、カテゴリを追加、管理する方法について説明します。

カテゴリを探索する

カテゴリを表示するには、コンソールまたは curl コマンドを使用します。

コンソール

[カテゴリ] ページを表示するには:

  1. [公開] > [ポータル] を選択し、目的のポータルを選択します。
  2. ポータルのホームページで、[API catalog] をクリックします。
    または、上部のナビゲーション バーにあるポータル プルダウン メニューから [API catalog] を選択します。
  3. [カテゴリ] タブをクリックします。API カタログの [カテゴリ] タブに、ポータルに定義されているカテゴリの一覧が表示されます。

    カテゴリ名、割り当てられた API の名前と合計数が表示された [カテゴリ] タブ

    カテゴリ名、割り当てられた API の名前と合計数が表示された [カテゴリ] タブ

    上の図でハイライト表示されているように、[API] ページでは次のことができます。

curl

organizations.sites.apicategories.list を使用してカテゴリを一覧表示するには:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal

レスポンス ペイロード:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

ここで

  • id:: カテゴリ アイテムの ID。例: 61c1014c-89c9-40e6-be3c-69cca3505620

カテゴリを追加する

カテゴリを追加するには:

コンソール

  1. [カテゴリ] ページにアクセスします
  2. [追加] をクリックします。
  3. 新しいカテゴリの名前を入力します。
  4. 必要に応じて、カテゴリタグを付ける API を 1 つ以上選択します。
  5. [作成] をクリックします。

curl

organizations.sites.apicategories.create を使用してカテゴリを追加するには:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • CATEGORY_NAME は、カテゴリの名前に置き換えます。例: demo-backend

レスポンス ペイロード:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

カテゴリを編集する

カテゴリを編集するには:

コンソール

  1. [カテゴリ] ページにアクセスします
  2. 編集するカテゴリにカーソルを合わせて、操作メニューを表示します。
  3. [ 編集] をクリックします。
  4. カテゴリの名前を編集します。
  5. API タグを追加または削除します。
  6. [保存] をクリックします。

curl

organizations.sites.apicategories.patch を使用してカテゴリを編集するには:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • CATEGORY_ID は、カテゴリの ID に置き換えます。例: bf6505eb-2a0f-47af-a00a-ded40ac72960list API categories コマンドを使用して、カテゴリ ID を取得します。
  • CATEGORY_NAME は、カテゴリの名前に置き換えます。例: demo-backend

レスポンス ペイロード:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

カテゴリを削除する

カテゴリを削除すると、そのカテゴリに付けた API タグもすべて削除されます。

カテゴリを削除するには:

コンソール

  1. [カテゴリ] ページにアクセスします
  2. 編集するカテゴリにカーソルを合わせて、操作メニューを表示します。
  3. [削除] をクリックします。
  4. [削除] をクリックして確定します。

curl

organizations.sites.apicategories.delete を使用してカテゴリを削除するには:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

次のように置き換えます。

  • ORG_NAME は、組織の名前に置き換えます。例: my-org
  • SITE_ID は、ORG_NAME-PORTAL_NAME 形式のポータルの名前に置き換えます。ORG_NAME は組織の名前、PORTAL_NAME は変換後のポータル名です。すべて小文字で、スペースとダッシュは削除します。例: my-org-myportal
  • CATEGORY_ID は、カテゴリの ID に置き換えます。例: bf6505eb-2a0f-47af-a00a-ded40ac72960list API categories コマンドを使用して、カテゴリ ID を取得します。

レスポンス ペイロード:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

公開済み API に関する問題のトラブルシューティング

以下のセクションでは、公開されている API に関する特定のエラーをトラブルシューティングに役立つ情報を示します。

エラー: [この API を試す] を使用した際に返される「Failed to fetch」エラー

[この API を試す] を使用して TypeError: Failed to fetch エラーが返された場合は、次の原因と解決策を検討してください。

  • 混合コンテンツ エラーの場合、そのエラーは swagger-ui の既知の問題が原因である可能性があります。考えられる回避策の一つは、OpenAPI ドキュメントの schemes 定義で、HTTPS を HTTP より前に指定していることです。次に例を示します。

    schemes:
       - https
       - http
    
  • クロスオリジン リソース シェアリング(CORS)制限エラーの場合は、API プロキシで CORS がサポートされていることを確認します。CORS は、クライアント側のクロスオリジン リクエストを可能にする標準の仕組みです。[この API を試す] パネルをサポートするように API プロキシを構成するをご覧ください。

エラー: Request header field not allowed

[この API を試す] の使用中に、次の例のような「Request header field not allowed」エラーが発生した場合は、CORS ポリシーでサポートされているヘッダーの更新が必要な可能性があります。次に例を示します。

field content-type is not allowed by Access-Control-Allow-Headers in preflight
response

この例では、content-type ヘッダーを CORS AssignMessage ポリシーの Access-Control-Allow-Headers セクションに追加する必要があります。詳細は、新しい API プロキシに Add CORS ポリシーを接続するをご覧ください。

エラー: OAuth 2.0 を使用して API プロキシを呼び出す際の「Access denied」

Google Cloud コンソールの OAuthV2 ポリシーは、RFC に準拠していない特定のプロパティを含むトークン レスポンスを返します。たとえば、このポリシーは、想定される RFC 準拠の値 Bearer ではなく、値が BearerToken のトークンを返します。[この API を試す] を使用している場合、無効な token_type レスポンスにより、「Access denied」エラーが発生する可能性があります。

この問題を修正するには、JavaScript または AssignMessage ポリシーを作成して、ポリシー出力を準拠する形式に変換します。詳細については、RFC に準拠していない動作をご覧ください。