Edge API를 사용하여 API 게시

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

이 섹션에서는 Edge 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 프록시에 대한 액세스를 제공하는 2개의 API 제품을 만들 수 있습니다. 동일한 API 프록시에 대한 액세스를 제공하지만 연결된 할당량 설정이 서로 다른 2개의 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/A No
approvalType API 제품에서 정의한 API에 액세스하기 위해 API 키가 승인되는 방식을 지정합니다. manual로 설정하면 앱에 대해 생성되는 키가 '대기 중' 상태가 됩니다. 이러한 키는 명시적으로 승인될 때까지 작동하지 않습니다. auto로 설정하면 모든 키가 '승인됨'에 생성되어 즉시 작동합니다. (auto는 일반적으로 제한된 할당량 또는 기능을 제공하는 무료/체험 API 제품에 대한 액세스를 제공하는 데 사용됩니다.) N/A 지원됨
attributes

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

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

다음은 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 제품을 보는 방법의 예시입니다.

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인 개발자의 프로필을 등록하고 개발자 만들기 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 제품에 대한 모든 요청의 일부로 이 사용자 인증 정보를 전달해야 합니다.

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

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