このセクションでは、Edge API を使用して API を公開する方法について説明します。
API を使用して API プロダクトを作成する
API プロダクトでは、デベロッパーは、API を使用するアプリを API キーと OAuth アクセス トークンで登録できます。API プロダクトでは、API リソースを「バンドル」し、異なるグループのデベロッパーにこれらのバンドルを公開することが可能です。たとえば、ある API リソースのセットはパートナー デベロッパーに公開し、別のバンドルは外部デベロッパーに公開する場合などが考えられます。API プロダクトでは、臨機応変にこのバンドルを実行可能で、API 自体への変更は不要です。アプリの新しいコンシューマ キーを取得しなくても、デベロッパーは「アップグレードされた」および「ダウングレードされた」バージョンにアクセスできるという利点もあります。
API を使用して API プロダクトを作成するには、/organizations/{org_name}/apiproducts に POST リクエストを発行します。詳細については、API プロダクトを作成する API リファレンスをご覧ください。
以下のリクエストでは、weather_free という API プロダクトを作成します。この API プロダクトは、test 環境にデプロイされている weatherapi という API プロキシで公開されている全 API へのアクセスを提供します。承認タイプは、auto に設定します。したがって、アクセス リクエストはすべて承認されます。
curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
"approvalType": "auto",
"displayName": "Free API Product",
"name": "weather_free",
"proxies": [ "weatherapi" ],
"environments": [ "test" ]
}' \
-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" : [ ] }
作成した前述の API プロダクトは、環境で API プロキシへのリクエストを認可する最も基本的なシナリオを実装します。これは、テスト環境で実行中の API プロキシを経由してアクセスされる全 API リソースをアクセス先として、認可されたアプリにアクセスを許可する API プロダクトを定義します。API プロダクトは、さまざまなデベロッパー グループの API を対象としてアクセス制御をカスタマイズできるように、追加的な構成設定を公開しています。たとえば、異なる API プロキシへのアクセスを提供する 2 つの API プロダクトを作成できます。また同じ API プロキシへのアクセスを提供するが、異なるクォータ設定と関連付けて 2 つの API プロダクトを作成することもできます。
API プロダクトの構成設定
API プロダクトは、次の構成オプションを公開します。
| 名前 | 説明 | デフォルト | 要否 |
|---|---|---|---|
apiResources |
API プロダクトに「バンドル」される URI のカンマ区切りリストまたはリソースパス デフォルトでリソースパスは、 特定のパスを選択したり、ワイルドカードですべての下位パスを選択したりできます。ワイルドカード（/** および /*）がサポートされます。アスタリスク 2 個のワイルドカードは、すべての下位 URI を含むことを表します。1 個のアスタリスクは、1 つ下のレベルの URI のみを含むことを表します。 |
なし | × |
approvalType |
API プロダクトで定義された API へのアクセスのために API キーを承認する方法を指定します。manual に設定すると、アプリのために生成されるキーは「pending」状態になります。このようなキーは、明示的に承認されるまで使用できません。auto に設定すると、すべてのキーは「approved」で生成され、すぐに使用できます（一般的に auto は、クォータや機能が制限される無料/トライアルの API プロダクトにアクセスを提供するために使用されます）。 |
なし | ○ |
attributes |
一連の属性。お客様固有のメタデータで API プロダクトのデフォルト プロファイルを拡張するために使用できます。
このプロパティを使用して、public、private、internal など、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 |
クォータをカウントする時間単位（分、時間、日、または月）。 | なし | × |
以下は、API プロダクトを作成するための詳細な例です。
curl -X POST https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -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
レスポンスの例
{ "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 プロダクトで定義された全スコープの集合体です。
API プロダクトを表示する
API を使用して組織に対して作成された API プロダクトを表示するには、次のセクションをご覧ください。
- API プロダクトを表示する（収益化済み）
デフォルトでは、収益化された API プロダクト（料金プランが 1 つ以上公開されている API プロダクト）のみが表示されます。すべての API プロダクトを表示するには、
monetizedクエリ パラメータをfalseに設定します。これは、収益化されていない List API プロダクト API に対して GET リクエストを発行することと同じです。https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true - API プロダクトを表示する（収益化されていない）
- デベロッパーを対象とする API プロダクトを表示する
- 会社を対象とする API プロダクトを表示する
次に、API を使用して API プロダクトを表示する方法の例を示します。
curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
-H "Accept:application/json" \
-u email:password
レスポンスは次のようになります（レスポンスの一部のみが表示されています）。
{
"product" : [ {
"customAtt1Name" : "user",
"customAtt2Name" : "response size",
"customAtt3Name" : "content-length",
"description" : "payment api product",
"displayName" : "payment",
"id" : "payment",
"name" : "payment",
"organization" : {
...
},
"pricePoints" : [ ],
"status" : "CREATED",
"transactionSuccessCriteria" : "status == 'SUCCESS'"
}, {
"customAtt1Name" : "user",
"customAtt2Name" : "response size",
"customAtt3Name" : "content-length",
"description" : "messaging api product",
"displayName" : "messaging",
"id" : "messaging",
"name" : "messaging",
"organization" : ...
},
"pricePoints" : [ ],
"status" : "CREATED",
"transactionSuccessCriteria" : "status == 'SUCCESS'"
} ],
"totalRecords" : 2
}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" }
API を使用してデベロッパー アプリを登録する
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 プロダクト、コンシューマ キー、およびシークレット）は、アプリ プロファイルの一部として返されます。組織の管理者は、いつでもコンシューマ キーを取得できます。
アプリ プロファイルには、コンシューマ キーとシークレットの値、コンシューマ キーのステータス、さらにキーのための 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 キーポリシーを確認するをご覧ください。
- OAuthV1、「VerifyAccessToken」オペレーション: 署名の検証、OAuth 1.0a アクセス トークンと「コンシューマ キー」の検証、アプリと API プロダクトの照合を実行します。詳細については、OAuth v1.0a ポリシーをご覧ください。
- OAuthV2、「VerifyAccessToken」オペレーション: OAuth 2.0 アクセス トークンが有効であることを検証し、トークンとアプリを照合して、アプリが有効であることを検証します。次に、アプリと API プロダクトを照合します。詳細については、OAuth ホームをご覧ください。
ポリシーと API プロダクトを構成すると、次のプロセスが Apigee Edge によって実行されます。
- リクエストは Apigee Edge によって受信され、適切な API プロキシに転送されます。
- クライアントによって提供された API キーまたは OAuth アクセス トークンを検証するポリシーが実行されます。
- Edge は、API キーまたはアクセス トークンをアプリ プロファイルに解決します。
- Edge は、アプリと関連付けられた API プロダクトのリスト（該当する場合）を解決します。
- 一致する最初の API プロダクトが、値として Quota 変数に格納されます。
- API キーまたはアクセス トークンと一致する API プロダクトがない場合、リクエストが拒否されます。
- Edge は、API プロダクト設定とクォータ設定に応じて、URI ベースのアクセス制御（環境、API プロキシ、URI パス）を強制します。