Edge API を使用して API を公開する

このセクションでは、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 のカンマ区切りリストまたはリソースパスデフォルトでリソースパスは、`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 などのすべてのサブパスに対するリクエストをサポートします。このデフォルトの動作の変更については、API プロダクトを管理するをご覧ください。	なし	×
`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 パス）を強制します。

Edge API を使用して API を公開する

API を使用して API プロダクトを作成する

API プロダクトの構成設定

スコープについて

API プロダクトを表示する

API を使用してデベロッパーを登録する

API を使用してデベロッパー アプリを登録する

API を使用してアプリのコンシューマ キーを管理する

アプリ用のコンシューマ キー（API キー）を取得する

アプリとキーに API プロダクトを追加する

コンシューマ キーを承認する

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

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

API プロダクトの設定を強制する

API を使用してデベロッパーアプリを登録する

API を使用してアプリのコンシューマキーを管理する

アプリ用のコンシューマキー（API キー）を取得する

コンシューマキーを承認する

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

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