Edge 管理 API での API の公開

このトピックでは、API プロダクトの定義について説明します。API プロダクトでは、デベロッパーは、API を使用するアプリを API キーと OAuth アクセス トークンで登録できます。API プロダクトでは、API リソースを「バンドル」し、異なるグループのデベロッパーにこれらのバンドルを公開することが可能です。たとえば、ある API リソースのセットはパートナー デベロッパーに公開し、別のバンドルは外部デベロッパーに公開する場合などが考えられます。API プロダクトでは、臨機応変にこのバンドルを実行可能で、API 自体への変更は不要です。アプリの新しいコンシューマ キーを取得しなくても、デベロッパーは「アップグレードされた」および「ダウングレードされた」バージョンにアクセスできるという利点もあります。

UI での代用
このトピックでは、API プロダクト、アプリ、およびデベロッパーを Apigee Edge 管理 API を使用してプロビジョニングする方法を示します。また、Apigee Edge 管理 UI を使用して、API プロダクト、デベロッパー、およびアプリをプロビジョニングすることもできます。Edge 管理 UI を使用する手順については、API プロダクトの作成を参照してください。

API プロダクトの構成

Edge 管理 UI または Edge 管理 API を使用して API プロダクトを構成できます。API では、API プロダクトをプログラムで作成して管理できます。

Apigee Edge 管理 API を使用して最小限の API プロダクトを設定するには、API プロダクトの作成 API を使用して、組織内の /apiproducts リソースにペイロードの POST を実行します。

以下のリクエストでは、weather_free という API プロダクトを作成します。この API プロダクトは、test 環境にデプロイされている weatherapi という API プロキシで公開されている全 API へのアクセスを提供します。承認タイプは、auto に設定します。したがって、アクセス リクエストはすべて承認されます。

    $ curl -H "Content-Type:application/json" -X POST -d \
    '{
      "approvalType": "auto",
      "displayName": "Free API Product",
      "name": "weather_free",
      "proxies": [ "weatherapi" ],
      "environments": [ "test" ]
    }' \
    https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
    -u email:password
    

レスポンスの例:

    {
      "apiResources" : [ ],
      "approvalType" : "auto",
      "attributes" : [ ],
      "createdAt" : 1362759663145,
      "createdBy" : "developer@apigee.com",
      "displayName" : "Free API Product",
      "environments" : [ "test" ],
      "lastModifiedAt" : 1362759663145,
      "lastModifiedBy" : "developer@apigee.com",
      "name" : "weather_free",
      "proxies" : [ "weatherapi" ],
      "scopes" : [ ]
    }
    

ここでは、test という環境で実行する weatherapi という API プロキシへのアクセス制限に使用できる非常に基本的な API プロダクトを設定しました。

作成した前述の API プロダクトは、環境で API プロキシへのリクエストを認可する最も基本的なシナリオを実装します。これは、test 環境で実行中の API プロキシを経由してアクセスされる全 API リソースをアクセス先として、認可されたアプリにアクセスを許可する API プロダクトを定義します。API プロダクトは、さまざまなデベロッパー グループの API を対象としてアクセス制御をカスタマイズできるように、追加的な構成設定を公開しています。たとえば、異なる API プロキシへのアクセスを提供する 2 つの API プロダクトを作成できます。また同じ API プロキシへのアクセスを提供するが、異なるクォータ設定と関連付けて 2 つの API プロダクトを作成することもできます。

API プロダクトの構成設定

API プロダクトは、次の構成オプションを公開します。

名前 説明 デフォルト 必須
apiResources

API プロダクトに「バンドル」される URI のカンマ区切りリストまたはリソースパス

デフォルトでリソースパスは、proxy.pathsuffix 変数からマップされます。プロキシパス サフィックスは、ProxyEndpoint ベースパスに続く URI フラグメントとして定義されます。たとえば、後述のサンプル API プロダクトでは、apiResources 要素は /forecastrss になるように定義されています。この API プロキシに定義されたベースパスは /weather であるため、/weather/forecastrss へのリクエストのみがこの API プロダクトで許可されることになります。

特定のパスを選択したり、ワイルドカードですべての下位パスを選択したりできます。ワイルドカード(/** および /*)がサポートされます。アスタリスク 2 個のワイルドカードは、すべての下位 URI を含むことを表します。1 個のアスタリスクは、1 つ下のレベルの URI のみを含むことを表します。

デフォルトの '/' は、API プロキシで定義されたベースパスとともに、'/**' と同じリソースをサポートします。たとえば、API プロキシのベースパスが /v1/weatherapikey の場合、API プロダクトは /v1/weatherapikey へのリクエストと、/v1/weatherapikey/forecastrss/v1/weatherapikey/region/CA などのすべてのサブ URI へのリクエストをサポートします。このデフォルトの動作の変更についての詳細は、API プロダクトの作成をご覧ください。

なし ×
approvalType API プロダクトで定義された API へのアクセスのために API キーを承認する方法を指定します。manual に設定すると、アプリのために生成されるキーは「pending」状態になります。このようなキーは、明示的に承認されるまで使用できません。auto に設定すると、すべてのキーが「approved」状態で生成され、すぐに使用できます(一般的に auto は、クォータや機能が制限される無料 / トライアルの API プロダクトにアクセスを提供するために使用されます)。 なし
attributes

一連の属性。お客様固有のメタデータで API プロダクトのデフォルト プロファイルを拡張するために使用できます。

このプロパティを使用して、publicprivateinternal など、API プロダクトのアクセスレベルを指定します。次に例を示します。
"attributes": [
{
"name": "access",
"value": "public"
},
{
"name": "foo",
"value": "foo"
},
{
"name": "bar",
"value": "bar"
}
]
なし ×
scopes ランタイム時に検証される OAuth スコープのカンマ区切りリスト。Apigee Edge は、提供された全アクセス トークンのスコープが API プロダクトで設定されたスコープと一致することを検証します。 なし ×
proxies 目的の API プロダクトをバインドする名前付きの API プロキシ。プロキシを指定することで、API プロダクト内のリソースと特定の API プロキシを関連付けて、デベロッパーが他の API プロキシ経由でこれらのリソースにアクセスできないようにします。 なし ×。定義されていない場合、apiResources を明示的に定義する必要があります(上の apiResources の情報をご覧ください)。flow.resource.name 変数は AssignMessage ポリシーに設定されています。
environments 目的の API プロダクトをバインドする名前付きの環境(「test」、「prod」など)。1 つ以上の環境を指定することで、API プロダクトにリストされたリソースを特定の環境にバインドして、デベロッパーが別の環境の API プロキシ経由でこれらのリソースにアクセスできないようにできます。たとえば、「test」にデプロイされた API プロキシが、「prod」内の API プロキシと関連付けられたリソースにアクセスできないようにする場合、この設定を使用します。 なし ×。定義されていない場合、apiResources を明示的に定義する必要があります。flow.resource.name 変数は AssignMessage ポリシーに設定されています。
quota 指定された時間間隔でアプリあたりに許可されるリクエスト数。 なし ×
quotaInterval クォータを評価する時間単位の数。 なし ×
quotaTimeUnit クォータをカウントする時間単位(分、時間、日、または月)。 なし ×
    $ curl -H "Content-Type:application/json" -X POST -d \
     '{
      "apiResources": [ "/forecastrss" ],
      "approvalType": "auto",
      "attributes":
        [ {"name": "access", "value": "public"} ],
      "description": "Free API Product",
      "displayName": "Free API Product",
      "name": "weather_free",
      "scopes": [],
      "proxies": [ "weatherapi" ],
      "environments": [ "test" ],
      "quota": "10",
      "quotaInterval": "2",
      "quotaTimeUnit": "hour" }' \
    -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts
    

レスポンスの例:

    {
      "apiResources" : [ "/forecastrss" ],
      "approvalType" : "auto",
      "attributes" : [ {
        "name" : "access",
        "value" : "public"
      },
      "createdAt" : 1344454200828,
      "createdBy" : "admin@apigee.com",
      "description" : "Free API Product",
      "displayName" : "Free API Product",
      "lastModifiedAt" : 1344454200828,
      "lastModifiedBy" : "admin@apigee.com",
      "name" : "weather_free",
      "scopes" : [ ],
      "proxies": [ {'weatherapi'} ],
      "environments": [ {'test'} ],
      "quota": "10",
      "quotaInterval": "1",
      "quotaTimeUnit": "hour"}'
    }
    

スコープに関する注意事項

スコープは、OAuth から派生したコンセプトであり、「権限」とだいたい同じ意味です。Apigee Edge では、スコープの使用は必須でなく、より詳細な認可を設定したい場合にスコープを使用できます。アプリに発行されるすべてのコンシューマ キーは、「マスター スコープ」と関連付けられています。マスター スコープは、アプリが承認された全 API プロダクトの全スコープのセットです。複数の API プロダクトの使用が承認されたアプリの場合、マスター スコープは、コンシューマ キーが承認された API プロダクトで定義された全スコープの集合体です。

デベロッパーの登録

すべてのアプリは、デベロッパーまたは会社に属します。したがって、アプリを作成するには、最初にデベロッパーまたは会社を登録する必要があります。

デベロッパーは、プロファイルの作成により組織に登録されます。プロファイルに含まれるデベロッパー メールが、Apigee Edge 全体でデベロッパーの一意キーとして使用されることに注意してください。

収益化をサポートするには、デベロッパーを作成または編集するときにマネタイズ属性を定義する必要があります。他の任意の属性を定義して、カスタム アナリティクス、カスタム ポリシーの強制などに使用することもできます。これらの任意の属性は、Apigee Edge では解釈されません。

たとえば、以下のリクエストは、メールアドレスが ntesla@theremin.com のデベロッパーのプロファイルを登録し、Create Developer API を使用してマネタイズ属性のサブセットを定義します。

    $ curl -H "Content-type:application/json" -X POST -d \
    '{"email" : "ntesla@theremin.com",
      "firstName" : "Nikola",
      "lastName" : "Tesla",
      "userName" : "theremin",
      "attributes" : [
      {
        "name" : "project_type",
        "value" : "public"
      },
      {
       "name": "MINT_BILLING_TYPE",
       "value": "POSTPAID"
      },
      {
       "name": "MINT_DEVELOPER_ADDRESS",
       "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
      },
      {
       "name": "MINT_DEVELOPER_TYPE",
       "value": "TRUSTED"
      },
      {
       "name": "MINT_HAS_SELF_BILLING,
       "value": "FALSE"
      },
      {
       "name" : "MINT_SUPPORTED_CURRENCY",
       "value" : "usd"
      }
     ]
    }' \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
    -u email:password
    

レスポンスの例:

    {
              "email" : "ntesla@theremin.com",
              "firstName" : "Nikola",
              "lastName" : "Tesla",
              "userName" : "theremin",
              "organizationName" : "{org_name}",
              "status" : "active",
              "attributes" : [
              {
                "name" : "project_type",
                "value" : "public"
              },
              {
                 "name": "MINT_BILLING_TYPE",
                 "value": "POSTPAID"
              },
              {
                 "name": "MINT_DEVELOPER_ADDRESS",
                 "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
              },
              {
                 "name": "MINT_DEVELOPER_TYPE",
                 "value": "TRUSTED"
              },
              {
                 "name": "MINT_HAS_SELF_BILLING,
                 "value": "FALSE"
              },
              {
                 "name" : "MINT_SUPPORTED_CURRENCY",
                 "value" : "usd"
              }
              ],
              "createdAt" : 1343189787717,
              "createdBy" : "admin@apigee.com",
              "lastModifiedAt" : 1343189787717,
              "lastModifiedBy" : "admin@apigee.com"
            }
    

デベロッパー アプリの登録

Apigee Edge に登録されるすべてのアプリは、デベロッパーおよび API プロダクトに関連付けられます。デベロッパーのためにアプリが登録されるとき、Apigee Edge はこのアプリを識別する「認証情報」(コンシューマ キーとシークレットのペア)を生成します。これ以降アプリは、アプリと関連付けられた API プロダクトに対するすべてのリクエストの一部として、これらの認証情報を渡す必要があります。

次のリクエストでは、作成した前述のデベロッパー(ntesla@theremin.com)のために、Create Developer App API を使用してアプリを登録します。アプリの登録時に、アプリの名前 callbackUrl と 1 つ以上の API プロダクトのリストを定義します。
    $ curl -H "Content-type:application/json" -X POST -d \
    '{
      "apiProducts": [ "weather_free"],
      "callbackUrl" : "login.weatherapp.com",
      "keyExpiresIn" : "2630000000",
      "name" : "weatherapp"}' \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
    -u email:password
    

callbackUrl は、アプリからのリダイレクト リクエストを検証するために、一部の OAuth 権限付与タイプ(認可コードなど)で使用されます。OAuth を使用する場合、この値を、OAuth リクエストの作成に使用される redirect_uri と同じ値に設定する必要があります。

keyExpiresIn 属性は、デベロッパー アプリのために生成されるコンシューマ キーの有効時間をミリ秒で指定します。デフォルト値 -1 は、有効時間が無期限であることを表します。

レスポンスの例:

    {
      "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1",
      "attributes": [
        {
          "name": "DisplayName",
          "value": "Test Key Expires"
        },
        {
          "name": "Notes",
          "value": "Just testing this attribute"
        }
      ],
      "createdAt": 1421770824390,
      "createdBy": "wwitman@apigee.com",
      "credentials": [
        {
          "apiProducts": [
            {
              "apiproduct": "ProductNoResources",
              "status": "approved"
            }
          ],
          "attributes": [],
          "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt",
          "consumerSecret": "AX7lGGIRJs6s8J8y",
          "expiresAt": 1424400824401,
          "issuedAt": 1421770824401,
          "scopes": [],
          "status": "approved"
        }
      ],
      "developerId": "e4Oy8ddTo3p1BFhs",
      "lastModifiedAt": 1421770824390,
      "lastModifiedBy": "wwitman@apigee.com",
      "name": "TestKeyExpires",
      "scopes": [],
      "status": "approved"
    }
    

アプリのコンシューマ キーの管理

アプリ用のコンシューマ キー(API キー)の取得

アプリの認証情報(API プロダクト、コンシューマ キー、およびシークレット)は、アプリ プロファイルの一部として返されます。組織の管理者は、いつでもコンシューマ キーを取得できます。

アプリ プロファイルには、コンシューマ キーとシークレットの値、コンシューマ キーのステータス、さらにキーのための API プロダクトの関連付けが表示されます。管理者は、Get Key Details for a Developer App API を使用して、いつでもコンシューマ キー プロファイルを取得できます。

    $ curl -X GET -H "Accept: application/json" \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
    -u email:password
    

レスポンスの例:

    {
      "apiProducts" : [ {
        "apiproduct" : "weather_free",
        "status" : "approved"
      } ],
      "attributes" : [ ],
      "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
      "consumerSecret" : "1eluIIdWG3JGDjE0",
      "status" : "approved"
    }
    

詳細については、Get Key Details for a Developer App を参照してください。

アプリおよびキーへの API プロダクトの追加

アプリを更新して新しい API プロダクトを追加するには、Add API Product to Key API を使用して、実際に API プロダクトをアプリのキーに追加します。詳細については、Add API Product to Key をご覧ください。

アプリキーに API プロダクトを追加すると、このキーを保持しているアプリは、API プロダクトでバンドルされた API リソースにアクセスできるようになります。次のメソッドの呼び出しでは、新しい API プロダクトをアプリに追加します。

    $ curl -H "Content-type:application/json" -X POST -d \
    '{
      "apiProducts": [ "newAPIProduct"]
    }' \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
    -u email:password
    

レスポンスの例:

    {
      "apiProducts": [
       {
         "apiproduct": "weather_free",
         "status": "approved"
       },
       {
         "apiproduct": "newAPIProduct",
         "status": "approved"
       }
     ],
     "attributes": [],
     "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
     "consumerSecret": "1eluIIdWG3JGDjE0",
     "expiresAt": -1,
     "issuedAt": 1411491156464,
     "scopes": [],
     "status": "approved"
     }
    

コンシューマ キーの承認

承認タイプを manual に設定すると、API プロダクトで保護されるリソースにアクセスできるデベロッパーを制御できます。API プロダクトでキー承認を manual に設定している場合、コンシューマ キーを明示的に承認する必要があります。Approve or Revoke Specific Key of Developer App API を使用して、キーを明示的に承認できます。

    $ curl -X POST -H "Content-type:appilcation/octet-stream" \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
    -u email:password
    

レスポンスの例:

    {
      "apiProducts" : [ {
      "apiproduct" : "weather_free",
      "status" : "approved"
    } ],
      "attributes" : [ ],
      "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
      "consumerSecret" : "1eluIIdWG3JGDjE0",
      "status" : "approved"
    }
    

詳細については、Approve or Revoke Specific Key of Developer App を参照してください。

コンシューマ キーに対する API プロダクトの承認

API プロダクトとコンシューマ キーの関連付けにもステータスがあります。API アクセスが正常に完了するには、コンシューマ キーが承認されており、さらに、適切な API プロダクトに対してそのコンシューマ キーが承認される必要があります。コンシューマ キーと API プロダクトの関連付けは、Approve or Revoke API Product for a Key for a Developer App API を使用して承認できます。

    $ curl -X POST -H "Content-type:application/octet-stream" \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
    -u email:password
    

この cURL コマンドはレスポンスを返しません。詳細については、Approve or Revoke API Product for a Key for a Developer App を参照してください。

コンシューマ キーに対する API プロダクトの取り消し

状況により、API プロダクトとコンシューマ キーの関連付けを取り消す必要がありますが、これには多くの理由があります。たとえば、デベロッパーが支払に応じない、トライアル期間が終了した、アプリが特定の API プロダクトから別の製品に昇格されたなど、これらの状況では、API プロダクトをコンシューマ キーから取り消す必要があります。

コンシューマ キーと API プロダクトの関連付けを取り消すには、Approve or Revoke Specific Key of Developer App API を使用して、デベロッパーのアプリのコンシューマ キーに対してアクション revoke を実行します。

    $ curl -X POST -H "Content-type:application/octet-stream" \
    https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
    -u email:password
    

この cURL コマンドはレスポンスを返しません。詳細については、Approve or Revoke Specific Key of Developer App を参照してください。

API プロダクト設定の強制

API プロダクトを強制するには、次のポリシータイプのいずれかを API プロキシフローに添付する必要があります。

  • VerifyAPIKey: API キーへの参照を取得して、有効なアプリが指定されていること、API プロダクトに一致することを検証します。詳細については、API Key ポリシーの検証をご覧ください。
  • OAuthV1、「VerifyAccessToken」オペレーション: 署名の検証、OAuth 1.0a アクセス トークンと「コンシューマ キー」の検証、アプリと API プロダクトの照合を実行します。詳細については、OAuth v1.0a ポリシーをご覧ください。
  • OAuthV2、「VerifyAccessToken」オペレーション: OAuth 2.0 アクセス トークンが有効であることを検証し、トークンとアプリを照合して、アプリが有効であることを検証します。次に、アプリと API プロダクトを照合します。詳細については、OAuth のホームページをご覧ください。

ポリシーと API プロダクトを構成すると、次のプロセスが Apigee Edge によって実行されます。

  1. リクエストは Apigee Edge によって受信され、適切な API プロキシに転送されます。
  2. クライアントによって提供された API キーまたは OAuth アクセス トークンを検証するポリシーが実行されます。
  3. Edge は、API キーまたはアクセス トークンをアプリ プロファイルに解決します。
  4. Edge は、アプリと関連付けられた API プロダクトのリスト(該当する場合)を解決します。
  5. 一致する最初の API プロダクトが、値として Quota 変数に格納されます。
  6. API キーまたはアクセス トークンと一致する API プロダクトがない場合、リクエストが拒否されます。
  7. Edge は、API プロダクト設定とクォータ設定に応じて、URI ベースのアクセス制御(環境、API プロキシ、URI パス)を強制します。

ヘルプ

ご質問は Apigee カスタマー サポートにお寄せください。