Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Edge 管理 API での API の公開

このトピックでは、API 製品 (product) の定義について説明します。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 製品 (product) の作成」の API を使用して、組織 (organization) 内の /apiproducts リソースにペイロードの POST を実行します。

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

http://enterprise.apigee.com でのアカウント設定と一致するように、emailpasswordorg_name の値を変更することを忘れないでください。

$ 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 という環境 (environment) で実行する weatherapi という API プロキシへのアクセス制限に使用できる非常に基本的な API 製品を設定しました。

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

API 製品の構成設定

API 製品は、次の構成オプションを公開します。

Name 説明 デフォルト 必須であるかどうか
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 製品 (product) の作成」を参照してください。

該当なし
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 の情報を参照)、AssignMessage ポリシーで flow.resource.name 変数を設定する必要があります。
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 製品で定義された全スコープの集合体です。

デベロッパの登録

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

このセクションでは、デベロッパのためにアプリの登録方法について説明します。Companies API を使用して会社グループを設定し、Company Developers API を使用してデベロッパを会社に追加できます。詳細については、「Companies」および「Company Developers」を参照してください。

If you use the Developer Services portal, Apigee recommends that you create, edit, and delete developers on the portal itself, not using the Edge management API. For more information, see Add and manage user accounts.

Developers are registered in an organization by creating a profile. Note that the developer email that is included in the profile is used as the unique key for the developer throughout Apigee Edge.

To support monetization, you must define the monetization attributes when creating or editing developers. You can also define other arbitrary attributes for use in custom analytics, custom policy enforcement, and so on; these arbitrary attributes will not be interpreted by Apigee Edge, 

For example, the following request registers a profile for a developer whose email address is ntesla@theremin.com and defines a subset of monetization attributes using the 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": "テストキーは期限切れ"
    },
    {
      "name": "Notes",
      "value": "この属性の単なるテスト"
    }
  ],
  "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 でアプリを削除する方法については、「Delete Developer App」を参照してください。

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

アプリ用のコンシューマキー (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  

サンプルレスポンス:

{
  "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 製品設定は、VerifyAPIKey、OAuthV2、Quota など、一致するポリシーによって強制されます。これらのポリシーが API プロキシに添付されるまで、API 製品とクォータが Apigee Edge によって強制されることはありません。

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

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

ポリシーと 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 ベースのアクセス制御 (環境 (environment)、API プロキシ、URI パス) を強制します。

サポートを受ける

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

Help or comments?