Apigee API를 사용하여 API 게시

이 섹션에서는 Apigee API를 사용하여 API를 게시하는 방법을 설명합니다.

API를 사용하여 API 제품 만들기

API 제품은 개발자가 API 키 및 OAuth 액세스 토큰을 사용하여 API를 사용하는 앱을 등록할 수 있게 해줍니다. 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 프록시에 대한 액세스를 제공하는 API 제품 두 개를 만들 수 있습니다. 또한 동일한 API 프록시에 대한 액세스를 제공하지만 관련 할당량 설정이 다른 API 제품 두 개를 만들 수도 있습니다.

API 제품 구성 설정

API 제품은 다음 구성 옵션을 노출합니다.

이름 설명 기본값 필수?
apiResources

API 제품으로 '번들'된, 쉼표로 구분된 URI 또는 리소스 경로입니다.

기본적으로 리소스 경로는 proxy.pathsuffix 변수에서 매핑됩니다. 프록시 경로 서픽스는 ProxyEndpoint 기본 경로 다음에 오는 URI 조각으로 정의됩니다. 예를 들어 아래 샘플 API 제품에서 apiResources 요소는 /forecastrss로 정의됩니다. 이 API 프록시에 정의된 기본 경로는 /weather이므로 이 API 제품에서는 /weather/forecastrss에 대한 요청만 허용됩니다.

특정 경로를 선택하거나 와일드 카드가 있는 모든 하위 경로를 선택할 수 있습니다. 와일드 카드(/** 및 /*)가 지원됩니다. 이중 별표 와일드 카드는 모든 하위 URI가 포함되어 있음을 나타냅니다. 별표가 한 개만 있는 경우 한 수준 아래 URI만 포함됩니다.

기본적으로 '/'는 '/**'와 동일한 리소스 및 API 프록시에서 정의한 기본 경로를 지원합니다. 예를 들어 API 프록시의 기본 경로가 /v1/weatherapikey이면 API 제품은 /v1/weatherapikey와 모든 하위 URI(예: /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA 등)에 대한 요청을 지원합니다. 이 기본값의 동작 변경에 대한 자세한 내용은 API 제품 관리를 참조하세요.

해당 없음 N
approvalType API 제품이 정의한 API에 액세스할 수 있도록 API 키를 승인하는 방법을 지정합니다. manual로 설정하면 앱용으로 생성된 키는 '대기중' 상태가 됩니다. 이러한 키는 명시적으로 승인될 때까지 작동하지 않습니다. auto로 설정하면 모든 키가 '승인됨'에서 생성되고 바로 작동합니다. (일반적으로 auto는 제한된 할당량 또는 기능을 제공하는 무료/평가판 API 제품에 대한 액세스를 제공하는 데 사용됩니다.) 해당 없음
attributes

고객별 메타데이터로 기본 API 제품 프로필을 확장하는 데 사용할 수 있는 속성의 배열입니다.

이 속성을 사용하여 API 제품의 액세스 수준을 public, private, internal로 지정합니다. 예:
"attributes": [
{
"name": "access",
"value": "public"
},
{
"name": "foo",
"value": "foo"
},
{
"name": "bar",
"value": "bar"
}
]
해당 없음 N
scopes 런타임 시 검증되는, 쉼표로 구분된 OAuth 범위 목록입니다. (Apigee는 표시된 모든 액세스 토큰의 범위가 API 제품에 설정된 범위와 일치하는지 확인합니다.) 해당 없음 N
proxies 이 API 제품이 바인딩된, 이름이 지정된 API 프록시입니다. 프록시를 지정하면 API 제품의 리소스를 특정 API 프록시와 연결하여 개발자는 다른 API 프록시를 통해 해당 리소스에 액세스할 수 없습니다. 해당 없음 아니요. 정의되지 않은 경우 apiResources는 명시적으로 정의되고(위의 apiResources의 정보 참조) AssignMessage 정책에 flow.resource.name 변수가 설정되어야 합니다.
environments 이 API 제품이 결합된 이름이 지정된 환경(예: 'test'또는 'prod')입니다. 환경을 한 개 이상 지정하면 API 제품에 나열된 리소스를 특정 환경에 결합하여 개발자가 다른 환경의 API 프록시를 통해 리소스에 액세스하지 못하도록 할 수 있습니다. 예를 들어 이 설정은 'prod'의 API 프록시와 연결된 리소스를 'test'에 배포된 API 프록시에서 액세스하지 못하도록 하는 데 사용됩니다. 해당 없음 아니요. 정의되지 않은 경우 apiResources는 명시적으로 정의되고 AssignMessage 정책에 flow.resource.name 변수가 설정되어야 합니다.
quota 지정된 시간 간격에 따라 앱별로 허용되는 요청 수입니다. 해당 없음 N
quotaInterval 할당량을 평가하는 시간 단위 수 해당 없음 N
quotaTimeUnit 할당량이 계산되는 시간 단위(분, 시간, 일 또는 월)입니다. 해당 없음 N

다음은 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에서 범위는 완전히 선택사항입니다. 범위를 사용하여 세분화된 승인을 얻을 수 있습니다. 앱에 발급되는 모든 고객 키는 '마스터 범위'와 연결됩니다. 마스터 범위는 이 앱의 모든 API 제품에 있는 모든 범위의 집합입니다. 여러 API 제품을 사용하도록 승인된 앱의 경우 마스터 범위는 고객 키가 승인된 API 제품에 정의된 모든 범위의 조합입니다.

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 전역에서 개발자의 고유 키로 사용됩니다.

수익 창출을 지원하려면 개발자를 만들거나 수정할 때 수익 창출 속성을 정의해야 합니다. 커스텀 애널리틱스, 커스텀 정책 적용 등에 사용할 다른 임의 속성을 정의할 수도 있습니다. 이러한 임의 속성은 Apigee에서 해석되지 않습니다.

예를 들어 다음 요청에서는 이메일 주소가 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에 등록된 모든 앱은 개발자 및 API 제품과 연결됩니다. 앱이 개발자를 대신해 등록되면 Apigee는 앱을 식별하는 '사용자 인증 정보'(고객 키 및 보안 비밀 쌍)를 생성합니다. 그런 다음 앱은 이러한 사용자 인증 정보를 앱과 연결된 API 제품에 대한 모든 요청의 일부로 전달해야 합니다.

다음 요청에서는 Create Developer App API를 사용하여 위에서 만든 개발자용 앱을 등록합니다(ntesla@theremin.com). 앱을 등록할 때 앱의 이름, callbackUrl, 하나 이상의 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를 사용하는 경우 이 값을 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 제품 연결이 표시됩니다. 관리자는 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"
}

자세한 내용은 개발자 앱의 키 세부정보 가져오기를 참조하세요.

앱 및 키에 API 제품 추가

새로운 API 제품을 추가하도록 앱을 업데이트하려면 Key API에 API 제품 추가를 사용하여 API 제품을 앱의 키에 실제로 추가합니다. 자세한 내용은 키에 API 제품 추가를 참조하세요.

앱 키에 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"
 }

고객 키 승인

승인 유형을 수동으로 설정하면 API 제품으로 보호되는 리소스에 액세스할 수 있는 개발자를 제어할 수 있습니다. API 제품의 키 승인이 manual로 설정되면 고객 키를 명시적으로 승인해야 합니다. 키는 개발자 앱의 특정 키 승인 또는 취소 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"
}

자세한 내용은 개발자 앱의 특정 키 승인 또는 취소를 참조하세요.

고객 키용 API 제품 승인

API 제품과 고객 키를 연결하는 경우에도 상태가 있습니다. API 액세스가 성공하려면 고객 키가 승인되어야 합니다. 그리고 고객 키는 적절한 API 제품에 대해 승인되어야 합니다. 개발자 앱 키의 API 제품 승인 또는 취소 API를 사용하여 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 명령어는 응답을 반환하지 않습니다. 자세한 내용은 개발자 앱용 키의 API 제품 승인 또는 취소를 참조하세요.

고객 키의 API 제품 취소

API 제품과 고객 키의 연결을 취소해야 하는 이유는 여러 가지가 있습니다. 개발자의 미결제, 만료된 체험 기간 또는 앱이 한 API 제품에서 다른 API 제품으로 승격된 경우 고객 키에서 API 제품을 삭제해야 할 수 있습니다.

API 제품과 고객 키의 연결을 취소하려면 개발 앱의 고객 키에 대해 작업 취소를 사용하여 개발자 앱의 특정 키 승인 또는 취소 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=revoke" \
-u email:password

이 cURL 명령어는 응답을 반환하지 않습니다. 자세한 내용은 개발자 앱의 특정 키 승인 또는 취소를 참조하세요.

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에서 다음 프로세스를 실행합니다.

  1. Apigee에서 요청을 수신하고 적절한 API 프록시로 라우팅합니다.
  2. 클라이언트가 제공한 API 키 또는 OAuth 액세스 토큰을 확인하는 정책이 실행됩니다.
  3. Apigee는 API 프로필에 대한 API 키 또는 액세스 토큰을 확인합니다.
  4. Apigee는 앱과 연결된 API 제품의 목록을 확인합니다(있는 경우).
  5. 일치하는 첫 번째 API 제품은 할당량 변수를 채우는 데 사용됩니다.
  6. API 키 또는 액세스 토큰과 일치하는 API 제품이 없으면 요청이 거부됩니다.
  7. Apigee에서는 할당량 설정을 비롯해 API 제품 설정에 따라 URI 기반 액세스 제어(환경, API 프록시, URI 경로)를 적용합니다.