Triển khai proxy API bằng API

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Mỗi tổ chức đều có một vòng đời phát triển phần mềm (SDLC) riêng. Thường thì bạn cần đồng bộ hoá và điều chỉnh việc triển khai proxy API với các quy trình được dùng cho dịch vụ phụ trợ.

Bạn có thể sử dụng các phương thức Edge API được minh hoạ trong chủ đề này để tích hợp hoạt động quản lý proxy API vào SDLC của tổ chức. Một trường hợp sử dụng phổ biến của API này là viết tập lệnh hoặc mã triển khai các proxy API, hoặc di chuyển các proxy API từ môi trường này sang môi trường khác, trong quy trình tự động hoá lớn hơn cũng triển khai hoặc di chuyển các ứng dụng khác.

Edge API không đưa ra giả định nào về SDLC của bạn (hoặc của bất kỳ ai khác). Thay vào đó, nó sẽ hiển thị các hàm nguyên tử mà nhóm phát triển của bạn có thể điều phối để tự động hoá và tối ưu hoá vòng đời phát triển API.

Để biết toàn bộ thông tin, hãy xem Edge API.

Để sử dụng Edge API, bạn phải xác thực danh tính của mình trong các lệnh gọi. Bạn có thể thực hiện việc này bằng một trong các phương thức sau:

  • OAuth2 (Chỉ dành cho Đám mây công khai)
  • SAML (Đám mây công cộng và đám mây riêng tư)
  • Xác thực cơ bản (không nên dùng; Đám mây công khai và riêng tư)

Chủ đề này tập trung vào tập hợp các API dùng để quản lý các proxy API.

Video: Xem video ngắn này để tìm hiểu cách triển khai một API.

Tương tác với API

Các bước sau đây sẽ hướng dẫn bạn cách tương tác đơn giản với các API.

Liệt kê các API trong tổ chức của bạn

Bạn có thể bắt đầu bằng cách liệt kê tất cả các proxy API trong tổ chức của mình. (Nhớ thay thế các mục cho EMAIL:PASSWORD và ORG_NAME. Để biết hướng dẫn, hãy xem bài viết Sử dụng Edge API.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Phản hồi mẫu:

[ "weatherapi" ]

Nhận API

Bạn có thể gọi phương thức GET trên mọi proxy API trong tổ chức của mình. Lệnh gọi này trả về danh sách tất cả các bản sửa đổi hiện có của proxy API.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Phản hồi mẫu:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

Thông tin chi tiết duy nhất mà phương thức này trả về là tên của API proxy cùng với bản sửa đổi được liên kết (có một số được liên kết). Các proxy API bao gồm một gói tệp cấu hình. Bản sửa đổi cung cấp một cơ chế đơn giản để quản lý các bản cập nhật cấu hình khi bạn lặp lại. Các bản sửa đổi được đánh số tuần tự, cho phép bạn huỷ một thay đổi bằng cách triển khai một bản sửa đổi trước đó của API proxy. Ngoài ra, bạn có thể triển khai một bản sửa đổi của một proxy API vào môi trường sản xuất, trong khi tiếp tục tạo các bản sửa đổi mới của proxy API đó trong môi trường kiểm thử. Khi đã sẵn sàng, bạn có thể quảng bá bản sửa đổi cao hơn của API proxy từ môi trường thử nghiệm lên bản sửa đổi trước đó của API proxy trong môi trường sản xuất.

Trong ví dụ này, chỉ có một bản sửa đổi vì proxy API vừa được tạo. Khi một proxy API chuyển qua vòng đời của quá trình triển khai và định cấu hình lặp lại, số phiên bản sẽ tăng lên theo số nguyên. Khi triển khai bằng cách sử dụng các lệnh gọi API trực tiếp, bạn có thể tăng số phiên bản của API proxy (không bắt buộc). Đôi khi, khi thực hiện các thay đổi nhỏ, bạn có thể không muốn tăng số phiên bản.

Nhận bản sửa đổi API

Phiên bản API (ví dụ: api.company.com/v1) rất hiếm khi thay đổi. Khi bạn tăng phiên bản API, điều này cho thấy đã có một thay đổi đáng kể trong chữ ký của giao diện bên ngoài do API này cung cấp.

Bản sửa đổi của proxy API là một số gia tăng được liên kết với cấu hình proxy API. Dịch vụ API duy trì các bản sửa đổi cấu hình để bạn có thể khôi phục cấu hình khi có vấn đề xảy ra. Theo mặc định, phiên bản của một API proxy sẽ tự động tăng lên mỗi khi bạn nhập một API proxy bằng cách sử dụng API Nhập một API proxy. Nếu không muốn tăng số phiên bản của một proxy API, hãy sử dụng API Cập nhật phiên bản proxy API. Nếu bạn đang sử dụng Maven để triển khai, hãy dùng các lựa chọn clean hoặc update, như mô tả trong tệp readme của trình bổ trợ Maven.

Ví dụ: bạn có thể gọi phương thức GET trên bản sửa đổi 1 của proxy API để xem thông tin chi tiết.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Phản hồi mẫu

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Các phần tử cấu hình proxy API này được ghi lại chi tiết trong Tài liệu tham khảo về cấu hình proxy API.

Triển khai một API vào một môi trường

Sau khi định cấu hình proxy API để nhận và chuyển tiếp yêu cầu đúng cách, bạn có thể triển khai proxy đó vào một hoặc nhiều môi trường. Thông thường, bạn sẽ lặp lại các proxy API trong test rồi khi đã sẵn sàng, bạn sẽ quảng bá bản sửa đổi proxy API lên prod. Thông thường, bạn sẽ thấy rằng bạn có nhiều bản sửa đổi hơn của một proxy API trong môi trường thử nghiệm, chủ yếu là do bạn sẽ thực hiện ít lần lặp lại hơn trong môi trường sản xuất.

Bạn không thể gọi một proxy API cho đến khi proxy đó được triển khai vào một môi trường. Sau khi triển khai bản sửa đổi proxy API cho môi trường sản xuất, bạn có thể xuất bản URL prod cho các nhà phát triển bên ngoài.

Cách liệt kê các môi trường

Mọi tổ chức trong Apigee Edge đều có ít nhất hai môi trường: test và prod. Sự phân biệt này là tuỳ ý. Mục tiêu là cung cấp cho bạn một khu vực để xác minh rằng proxy API của bạn đang hoạt động đúng cách trước khi bạn mở proxy này cho các nhà phát triển bên ngoài.

Mỗi môi trường thực sự chỉ là một địa chỉ mạng, cho phép bạn phân tách lưu lượng truy cập giữa các proxy API mà bạn đang sử dụng và những proxy mà các ứng dụng đang truy cập trong thời gian chạy.

Môi trường cũng cung cấp sự phân tách dữ liệu và tài nguyên. Ví dụ: bạn có thể thiết lập các bộ nhớ đệm khác nhau trong quá trình kiểm thử và sản xuất, chỉ các proxy API thực thi trong môi trường đó mới có thể truy cập vào bộ nhớ đệm.

Xem các môi trường trong một tổ chức

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Phản hồi mẫu

[ "test", "prod" ]

Khám phá các loại hình triển khai

Việc triển khai là một bản sửa đổi của một proxy API đã được triển khai trong một môi trường. Bạn có thể truy cập vào một proxy API ở trạng thái đã triển khai qua mạng, tại các địa chỉ được xác định trong phần tử <VirtualHost> cho môi trường đó.

Triển khai các proxy API

Bạn không thể gọi các proxy API cho đến khi triển khai chúng. API Services cung cấp các API RESTful giúp kiểm soát quy trình triển khai.

Tại một thời điểm nhất định, chỉ có thể triển khai một bản sửa đổi của một proxy API trong một môi trường. Do đó, bạn cần huỷ triển khai bản sửa đổi đã triển khai. Bạn có thể kiểm soát việc gói mới được triển khai dưới dạng một bản sửa đổi mới hay ghi đè bản sửa đổi hiện có.

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Trước tiên, hãy huỷ triển khai bản sửa đổi hiện có. Chỉ định tên môi trường và số phiên bản của API proxy mà bạn muốn huỷ triển khai:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Sau đó, hãy triển khai bản sửa đổi mới. Bản sửa đổi mới của proxy API phải đã tồn tại: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Triển khai liền mạch (không có thời gian ngừng hoạt động)

Để giảm thiểu khả năng xảy ra thời gian ngừng hoạt động trong quá trình triển khai, hãy sử dụng tham số override trên phương thức triển khai và đặt tham số này thành true.

Bạn không thể triển khai một bản sửa đổi của một proxy API lên trên một bản sửa đổi khác. Phần tử đầu tiên phải luôn chưa được triển khai. Bằng cách đặt override thành true, bạn cho biết rằng một bản sửa đổi của một proxy API sẽ được triển khai trên bản sửa đổi hiện đang được triển khai. Kết quả là trình tự triển khai bị đảo ngược – bản sửa đổi mới được triển khai và sau khi quá trình triển khai hoàn tất, bản sửa đổi đã triển khai sẽ được huỷ triển khai.

Ví dụ sau đây đặt giá trị override bằng cách truyền giá trị này dưới dạng một tham số biểu mẫu: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

Bạn có thể tối ưu hoá thêm việc triển khai bằng cách đặt tham số delay. Tham số delay chỉ định một khoảng thời gian (tính bằng giây) trước khi bản sửa đổi trước đó được huỷ triển khai. Hiệu ứng là các giao dịch đang diễn ra có một khoảng thời gian để hoàn tất trước khi proxy API xử lý giao dịch của họ bị huỷ triển khai. Sau đây là những gì xảy ra với override=true và bộ tham số delay:

  • Bản sửa đổi 1 đang xử lý các yêu cầu.
  • Bản sửa đổi 2 đang được triển khai song song.
  • Khi Bản sửa đổi 2 được triển khai đầy đủ, lưu lượng truy cập mới sẽ được gửi đến Bản sửa đổi 2. Không có lưu lượng truy cập mới nào được gửi đến Bản sửa đổi 1.
  • Tuy nhiên, phiên bản 1 vẫn có thể đang xử lý các giao dịch hiện có. Bằng cách đặt tham số delay (ví dụ: 15 giây), bạn cho Bản sửa đổi 1 15 giây để hoàn tất việc xử lý các giao dịch hiện có.
  • Sau khoảng thời gian trễ, Bản sửa đổi 1 sẽ được huỷ triển khai.
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Tham số truy vấn Mô tả
override

Mặc định là false (hành vi triển khai thông thường: bản sửa đổi hiện có sẽ được huỷ triển khai, sau đó bản sửa đổi mới sẽ được triển khai).

Đặt thành true để ghi đè hành vi triển khai thông thường và cung cấp quy trình triển khai liền mạch. Bản sửa đổi hiện tại vẫn được triển khai trong khi bản sửa đổi mới cũng đang được triển khai. Khi bản sửa đổi mới được triển khai, bản sửa đổi cũ sẽ bị huỷ triển khai. Sử dụng cùng với tham số delay để kiểm soát thời điểm huỷ triển khai.
delay

Để cho phép quá trình xử lý giao dịch hoàn tất trên bản sửa đổi hiện có trước khi bản sửa đổi đó được huỷ triển khai và loại bỏ khả năng xảy ra 502 Bad Gateway hoặc 504 Gateway Timeout errors, hãy đặt tham số này thành số giây mà bạn muốn trì hoãn việc huỷ triển khai. Bạn có thể đặt số giây tuỳ ý và việc đặt số giây lớn sẽ không ảnh hưởng đến hiệu suất. Trong thời gian trễ, không có lưu lượng truy cập mới nào được gửi đến bản sửa đổi cũ.

Mặc định là 0 giây. Khi override được đặt thành true và delay là 0, bản sửa đổi hiện có sẽ được huỷ triển khai ngay sau khi bản sửa đổi mới được triển khai. Giá trị âm được coi là 0 (không) giây.

Khi bạn sử dụng override=true cùng với delay, bạn có thể loại bỏ các phản hồi HTTP 5XX trong quá trình triển khai. Lý do là cả hai bản sửa đổi của proxy API sẽ được triển khai đồng thời, trong đó bản sửa đổi cũ hơn sẽ được huỷ triển khai sau khi có độ trễ.

Xem tất cả các hoạt động triển khai của một Bản sửa đổi API

Đôi khi, bạn cần tìm nạp danh sách tất cả các bản sửa đổi hiện được triển khai của một proxy API.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

Phản hồi ở trên chứa nhiều thuộc tính dành riêng cho cơ sở hạ tầng nội bộ của Apigee Edge. Bạn không thể thay đổi các chế độ cài đặt này, trừ phi bạn đang sử dụng Apigee Edge tại chỗ.

Các thuộc tính quan trọng có trong phản hồi là organization, environment, aPIProxy, name và state. Bằng cách xem xét các giá trị thuộc tính này, bạn có thể xác nhận rằng một bản sửa đổi cụ thể của một proxy API được triển khai trong một môi trường.

Xem tất cả các bản triển khai trong môi trường thử nghiệm

Bạn cũng có thể truy xuất trạng thái triển khai cho một môi trường cụ thể (bao gồm cả số phiên bản của proxy API hiện đang được triển khai) bằng cách sử dụng lệnh gọi sau:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Thao tác này sẽ trả về kết quả tương tự như trên cho mọi API được triển khai trong môi trường thử nghiệm

Xem tất cả các hoạt động triển khai trong tổ chức của bạn

Để tìm nạp danh sách tất cả các bản sửa đổi hiện đang được triển khai của tất cả các proxy API trong mọi môi trường, hãy sử dụng phương thức API sau:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Thao tác này sẽ trả về kết quả tương tự như trên cho tất cả các proxy API được triển khai trong mọi môi trường.

Vì API này là RESTful, nên bạn chỉ cần sử dụng phương thức POST cùng với tải trọng JSON hoặc XML đối với cùng một tài nguyên để tạo một proxy API.

Một hồ sơ cho proxy API của bạn sẽ được tạo. Biểu thị mặc định của một proxy API là ở ký hiệu đối tượng JavaScript (JSON). Dưới đây là phản hồi JSON mặc định cho yêu cầu POST ở trên, yêu cầu này đã tạo một proxy API có tên là weatherapi. Sau đây là nội dung mô tả về từng phần tử trong hồ sơ:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Hồ sơ proxy API được tạo minh hoạ cấu trúc hoàn chỉnh của một proxy API:

  • APIProxy revision: Lần lặp lại được đánh số tuần tự của cấu hình proxy API, do Dịch vụ API duy trì
  • APIProxy name: Tên duy nhất của proxy API
  • ConfigurationVersion: Phiên bản Dịch vụ API mà cấu hình proxy API tuân thủ
  • CreatedAt: Thời gian tạo proxy API, được định dạng theo thời gian UNIX
  • CreatedBy: Địa chỉ email của người dùng Apigee Edge đã tạo proxy API
  • DisplayName: Tên thân thiện với người dùng cho proxy API
  • LastModifiedAt: Thời gian tạo proxy API, được định dạng theo thời gian UNIX
  • LastModifiedBy: Địa chỉ email của người dùng Apigee Edge đã tạo proxy API
  • Policies: Danh sách các chính sách đã được thêm vào proxy API này
  • ProxyEndpoints: Danh sách ProxyEndpoint được đặt tên
  • Resources: Danh sách các tài nguyên (JavaScript, Python, Java, XSLT) có thể được thực thi trong proxy API này
  • TargetServers: Danh sách TargetServer được đặt tên (có thể được tạo bằng API quản lý), được dùng trong các cấu hình nâng cao cho mục đích cân bằng tải
  • TargetEndpoints: Danh sách TargetEndpoint được đặt tên

Xin lưu ý rằng nhiều phần tử trong cấu hình proxy API được tạo bằng phương thức POST đơn giản ở trên là trống. Trong các chủ đề sau, bạn sẽ tìm hiểu cách thêm và định cấu hình các thành phần chính của một proxy API.

Bạn cũng có thể đọc về các phần tử cấu hình này trong tài liệu tham khảo về cấu hình proxy API.

Tạo tập lệnh dựa trên API

Sử dụng các proxy API mẫu, có sẵn trên GitHub cung cấp các tập lệnh shell bao bọc công cụ triển khai Apigee. Nếu vì lý do nào đó mà bạn không thể sử dụng công cụ triển khai Python, thì bạn có thể gọi trực tiếp API. Cả hai phương pháp đều được minh hoạ trong các tập lệnh mẫu bên dưới.

Gói công cụ triển khai

Trước tiên, hãy đảm bảo rằng công cụ triển khai Python có sẵn trong môi trường cục bộ của bạn.

Sau đó, hãy tạo một tệp để lưu trữ thông tin đăng nhập của bạn. Các tập lệnh triển khai mà bạn viết sẽ nhập các chế độ cài đặt này, giúp bạn quản lý thông tin đăng nhập cho tài khoản của mình một cách tập trung. Trong mẫu Nền tảng API, tệp này có tên là setenv.sh.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

Tệp ở trên cung cấp tất cả các chế độ cài đặt của bạn cho tập lệnh shell bao bọc công cụ triển khai.

Bây giờ, hãy tạo một tập lệnh shell nhập các chế độ cài đặt đó và sử dụng chúng để gọi công cụ triển khai. (Để xem ví dụ, hãy xem Các mẫu nền tảng API Apigee.)

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

Để cuộc sống của bạn thực sự dễ dàng, hãy tạo một tập lệnh để gọi và kiểm thử API, như sau:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Trực tiếp gọi API

Bạn có thể viết các tập lệnh shell đơn giản để tự động hoá quy trình tải lên và triển khai các proxy API.

Tập lệnh bên dưới sẽ trực tiếp gọi API quản lý. Lệnh này huỷ triển bản sửa đổi hiện có của API proxy mà bạn đang cập nhật, tạo một tệp ZIP từ thư mục /apiproxy chứa các tệp cấu hình proxy của bạn, sau đó tải lên, nhập và triển khai cấu hình.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST