Phát hành API bằng Edge API

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Phần này mô tả cách dùng API Edge để tạo sản phẩm API nhằm phát hành trong cổng thông tin dành cho nhà phát triển.

Tạo sản phẩm API bằng API

Các sản phẩm API cho phép nhà phát triển đăng ký những ứng dụng sử dụng API bằng khoá API và mã truy cập OAuth. Các sản phẩm API được thiết kế để cho phép bạn "gói" các tài nguyên API rồi phát hành những gói đó cho những nhóm nhà phát triển khác nhau. Ví dụ: có thể bạn cần phát hành một nhóm tài nguyên API cho nhà phát triển đối tác trong khi phát hành một gói khác cho nhà phát triển bên ngoài. Các sản phẩm API cho phép bạn thực hiện việc nhóm này một cách nhanh chóng mà không yêu cầu bất kỳ thay đổi nào đối với chính API của bạn. Một lợi ích khác là quyền truy cập của nhà phát triển có thể được "nâng cấp" và "hạ cấp" mà không yêu cầu nhà phát triển lấy khoá người dùng mới cho ứng dụng của họ.

Để tạo một sản phẩm API bằng API, hãy gửi yêu cầu POST đến /organizations/{org_name}/apiproducts. Để biết thêm thông tin, hãy xem Tài liệu tham khảo API về Tạo sản phẩm API.

Yêu cầu sau đây tạo ra một sản phẩm API có tên là weather_free. Sản phẩm API cung cấp quyền truy cập vào tất cả các API do proxy API hiển thị có tên là weatherapi (được triển khai trong môi trường test). Loại phê duyệt được đặt thành auto, cho biết rằng mọi yêu cầu cấp quyền truy cập đều sẽ được phê duyệt.

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 

Câu trả lời mẫu:

{
  "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" : [ ]
}

Sản phẩm API được tạo ở trên sẽ triển khai trường hợp cơ bản nhất, uỷ quyền các yêu cầu đến một proxy API trong một môi trường. Tệp này xác định một sản phẩm API cho phép một ứng dụng được uỷ quyền truy cập vào mọi tài nguyên API được truy cập thông qua proxy API đang chạy trong môi trường kiểm thử. Các sản phẩm API hiển thị các chế độ cài đặt cấu hình bổ sung cho phép bạn tuỳ chỉnh chế độ kiểm soát quyền truy cập vào các API cho nhiều nhóm nhà phát triển. Ví dụ: bạn có thể tạo hai sản phẩm API cung cấp quyền truy cập vào các proxy API khác nhau. Bạn cũng có thể tạo hai sản phẩm API cung cấp quyền truy cập vào cùng các proxy API, nhưng có các chế độ cài đặt Hạn mức khác nhau được liên kết.

Chế độ cài đặt cấu hình sản phẩm API

Các sản phẩm API hiển thị các tuỳ chọn cấu hình sau:

Sau đây là ví dụ chi tiết hơn về cách tạo một sản phẩm 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

Phản hồi mẫu

{
  "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"}'
}

Giới thiệu về phạm vi

Phạm vi là một khái niệm được lấy từ OAuth và ánh xạ gần đúng đến khái niệm "quyền". Trên Apigee Edge, bạn hoàn toàn không bắt buộc phải sử dụng phạm vi. Bạn có thể sử dụng phạm vi để uỷ quyền chi tiết hơn. Mỗi khoá người dùng được cấp cho một ứng dụng đều được liên kết với một "phạm vi chính". Phạm vi chính là tập hợp tất cả các phạm vi trong tất cả sản phẩm API cho vấn đề này mà ứng dụng đã được phê duyệt. Đối với các ứng dụng được phê duyệt để sử dụng nhiều sản phẩm API, phạm vi chính là hợp nhất tất cả các phạm vi được xác định trong những sản phẩm API mà khoá người dùng đã được phê duyệt.

Xem các sản phẩm API

Để xem các sản phẩm API được tạo cho một tổ chức bằng API, hãy xem các phần sau:

• Xem các sản phẩm API (có thể kiếm tiền)

  Theo mặc định, chỉ các sản phẩm API dùng để kiếm tiền mới xuất hiện (tức là các sản phẩm API có ít nhất một gói giá được phát hành). Để hiển thị tất cả sản phẩm API, hãy đặt tham số truy vấn monetized thành false. Điều này tương đương với việc gửi yêu cầu GET cho API sản phẩm List API không kiếm tiền: https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true

• Xem các sản phẩm API (không được kiếm tiền)
• Xem các sản phẩm API đủ điều kiện dành cho nhà phát triển
• Xem các sản phẩm API đủ điều kiện dành cho một công ty

Sau đây là ví dụ về cách xem các sản phẩm API bằng API:

curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
  -H "Accept:application/json" \
  -u email:password

Phản hồi sẽ có dạng như sau (chỉ hiển thị một phần nội dung của phản hồi):

{
  "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
}

Đăng ký nhà phát triển bằng API

Tất cả ứng dụng đều thuộc quyền sở hữu của nhà phát triển hoặc công ty. Do đó, để tạo một ứng dụng, trước tiên, bạn cần đăng ký với một nhà phát triển hoặc công ty.

Nhà phát triển được đăng ký trong tổ chức bằng cách tạo hồ sơ. Xin lưu ý rằng email của nhà phát triển có trong hồ sơ sẽ được dùng làm khoá duy nhất cho nhà phát triển xuyên suốt quá trình Apigee Edge.

Để hỗ trợ việc kiếm tiền, bạn phải xác định các thuộc tính kiếm tiền khi tạo hoặc chỉnh sửa nhà phát triển. Bạn cũng có thể xác định các thuộc tính tuỳ ý khác để dùng trong hoạt động phân tích tuỳ chỉnh, thực thi chính sách tuỳ chỉnh, v.v.; Apigee sẽ không diễn giải được các thuộc tính tuỳ ý này,

Ví dụ: yêu cầu sau đây đăng ký hồ sơ cho một nhà phát triển có địa chỉ email là ntesla@theremin.com và xác định một tập hợp con các thuộc tính kiếm tiền bằng cách sử dụng API Tạo nhà phát triển:

$ 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 

Phản hồi mẫu

{
          "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"
        }

Đăng ký ứng dụng của nhà phát triển bằng API

Mọi ứng dụng được đăng ký trên Apigee Edge đều được liên kết với một nhà phát triển và một sản phẩm API. Khi ứng dụng được đăng ký thay mặt cho nhà phát triển, Apigee Edge sẽ tạo một "thông tin xác thực" (cặp bí mật và khoá của người dùng) giúp nhận dạng ứng dụng. Sau đó, ứng dụng phải truyền những thông tin xác thực này trong mọi yêu cầu đến một sản phẩm API liên kết với ứng dụng.

$ 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 

Một số loại cấp quyền sử dụng OAuth (chẳng hạn như mã uỷ quyền) dùng callbackUrl để xác thực yêu cầu chuyển hướng từ ứng dụng. Nếu sử dụng OAuth, thì bạn phải đặt giá trị này thành cùng một giá trị với redirect_uri dùng để đưa ra yêu cầu OAuth.

Thuộc tính keyExpiresIn chỉ định (tính bằng mili giây) trong vòng đời của khoá người dùng sẽ được tạo cho ứng dụng của nhà phát triển. Giá trị mặc định -1 cho biết khoảng thời gian có hiệu lực vô hạn.

Phản hồi mẫu

{
  "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"
}

Quản lý khoá của người dùng cho các ứng dụng bằng API

Lấy khoá người dùng (Khoá API) cho ứng dụng

Thông tin xác thực của một ứng dụng (sản phẩm API, khoá bí mật và khoá người dùng) sẽ được trả về trong hồ sơ ứng dụng. Quản trị viên của một tổ chức có thể truy xuất khoá người dùng bất cứ lúc nào.

Hồ sơ ứng dụng hiển thị giá trị của khoá và thông tin bí mật của người dùng, trạng thái của khoá người dùng, cũng như mọi mối liên kết sản phẩm API cho khoá đó. Là quản trị viên, bạn có thể truy xuất hồ sơ khoá người dùng bất cứ lúc nào bằng cách sử dụng Get Key Details for a Developer App API (Lấy thông tin chi tiết về khoá cho API ứng dụng dành cho nhà phát triển):

$ 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

Phản hồi mẫu

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Xem bài viết Lấy thông tin chi tiết về khoá cho ứng dụng của nhà phát triển để biết thêm thông tin.

Thêm sản phẩm API vào ứng dụng và khoá

Để cập nhật một ứng dụng nhằm thêm sản phẩm API mới, bạn thực sự thêm sản phẩm API đó vào khoá của ứng dụng đó bằng cách sử dụng Add API Product to Key API (Thêm sản phẩm API vào khoá). Hãy xem bài viết Thêm sản phẩm API vào khoá để biết thêm thông tin.

Khi thêm sản phẩm API vào khoá ứng dụng, ứng dụng chứa khoá đó sẽ có thể truy cập vào các tài nguyên API đi kèm trong sản phẩm API. Lệnh gọi phương thức sau đây sẽ thêm một sản phẩm API mới vào một ứng dụng:

$ 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 

Câu trả lời mẫu:

{
  "apiProducts": [
   {
     "apiproduct": "weather_free",
     "status": "approved"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "status": "approved"
 }

Phê duyệt khoá của người dùng

Việc đặt loại phê duyệt thành thủ công sẽ cho phép bạn kiểm soát những nhà phát triển nào có thể truy cập vào các tài nguyên được các sản phẩm API bảo vệ. Khi các sản phẩm API có phê duyệt khoá được đặt thành manual, khoá người dùng phải được phê duyệt một cách rõ ràng. Bạn có thể phê duyệt khoá cụ thể bằng cách sử dụng API Phê duyệt hoặc thu hồi khoá cụ thể của ứng dụng dành cho nhà phát triển:

$ 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

Phản hồi mẫu

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Xem phần Phê duyệt hoặc thu hồi khoá cụ thể của ứng dụng của nhà phát triển để biết thêm thông tin.

Phê duyệt các sản phẩm API cho khoá của người dùng

Việc liên kết một sản phẩm API với khoá của người dùng cũng có trạng thái. Để quyền truy cập vào API thành công, khoá người dùng phải được phê duyệt và khoá người dùng phải được phê duyệt cho sản phẩm API thích hợp. Bạn có thể phê duyệt việc liên kết khoá người dùng với một sản phẩm API bằng cách sử dụng API Phê duyệt hoặc thu hồi sản phẩm API của khoá của ứng dụng dành cho nhà phát triển:

$ 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

Lệnh cURL này không trả về phản hồi. Để biết thêm thông tin, hãy xem bài viết Phê duyệt hoặc thu hồi sản phẩm API đối với khoá của một ứng dụng của nhà phát triển.

Thu hồi các sản phẩm API cho khóa người dùng

Có nhiều lý do khiến bạn cần phải thu hồi mối liên kết giữa khoá người tiêu dùng với một sản phẩm API. Bạn có thể cần phải xoá một sản phẩm API khỏi khoá của người tiêu dùng do nhà phát triển không thanh toán, do hết thời gian dùng thử hoặc khi một ứng dụng được quảng bá từ sản phẩm API này sang sản phẩm API khác.

Để thu hồi mối liên kết giữa khoá người dùng với một sản phẩm API, hãy sử dụng API Phê duyệt hoặc thu hồi khoá cụ thể của ứng dụng dành cho nhà phát triển , bằng cách sử dụng tính năng thu hồi hành động đối với khoá người dùng của ứng dụng nhà phát triển:

$ 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

Lệnh cURL này không trả về phản hồi. Xem phần Phê duyệt hoặc thu hồi khoá cụ thể của ứng dụng của nhà phát triển để biết thêm thông tin.

Thực thi chế độ cài đặt sản phẩm API

Để thực thi các sản phẩm API, bạn phải đính kèm một trong các loại chính sách sau vào quy trình proxy API:

• VerifyAPIKey: Tham chiếu đến một khoá API, xác minh rằng khoá này đại diện cho một ứng dụng hợp lệ và khớp với sản phẩm API. Xem Chính sách về khoá API để biết thêm thông tin.
• OAuthV1, thao tác “VerifyAccessToken”: Xác minh chữ ký, xác thực mã truy cập OAuth 1.0a và “khoá người dùng” rồi so khớp ứng dụng với sản phẩm API. Vui lòng xem Chính sách về OAuth phiên bản 1.0a để biết thêm thông tin.
• OAuthV2, thao tác “VerifyAccessToken”: Xác minh rằng mã truy cập OAuth 2.0 là hợp lệ, so khớp mã này với ứng dụng, xác minh rằng ứng dụng là hợp lệ, sau đó so khớp ứng dụng với một sản phẩm API. Xem trang chủ OAuth để biết thêm thông tin.

Sau khi bạn định cấu hình các chính sách và sản phẩm API, Apigee sẽ thực thi quy trình sau đây:

1. Apigee Edge đã nhận được một yêu cầu và chuyển đến proxy API thích hợp.
2. Một chính sách được thực thi để xác minh khoá API hoặc mã truy cập OAuth do ứng dụng cung cấp.
3. Edge phân giải Khoá API hoặc mã truy cập vào một hồ sơ ứng dụng.
4. Edge giải quyết danh sách (nếu có) các sản phẩm API liên kết với ứng dụng.
5. Sản phẩm API đầu tiên phù hợp được dùng để điền các biến Hạn mức.
6. Nếu không có sản phẩm API nào khớp với khoá API hoặc mã truy cập thì yêu cầu sẽ bị từ chối.
7. Edge thực thi chế độ kiểm soát quyền truy cập dựa trên URI (môi trường, proxy API và đường dẫn URI) dựa trên chế độ cài đặt sản phẩm API, cùng với chế độ cài đặt Hạn mức.