Triển khai proxy API bằng 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

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

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

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

Để biết đầy đủ thông tin, hãy xem bài viết API Edge.

Để sử dụng API Edge, bạn phải xác thực bản thân 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 pháp sau:

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

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

Tương tác với API

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

Liệt kê 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ả proxy API trong tổ chức của mình. (Nhớ thay thế cho EMAIL:PASSWORD và ORG_NAME. Để biết hướng dẫn, hãy xem Sử dụng API Edge.

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

Phản hồi mẫu:

[ "weatherapi" ]

Nhận một 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 duy nhất được phương thức này trả về là tên của proxy API cùng với bản sửa đổi, có số được liên kết. Proxy API bao gồm một nhóm cấu hình tệp. Bản sửa đổi cung cấp cơ chế gọn nhẹ để 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 hoàn nguyên thay đổi bằng cách triển khai bản sửa đổi trước đó của proxy API. Ngoài ra, bạn có thể triển khai bản sửa đổi proxy API vào môi trường thực tế, đồng thời tiếp tục tạo các bản sửa đổi mới của proxy API đó trong quá trình kiểm thử môi trường. Khi đã sẵn sàng, bạn có thể quảng bá bản sửa đổi cao hơn của proxy API từ kiểm thử môi trường thử nghiệm so với bản sửa đổi trước đó của proxy API trong môi trường sản phẩm.

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

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

Phiên bản API (ví dụ: api.company.com/v1) sẽ thay đổi rất thường xuyên. Khi bạn tăng phiên bản API, điều đó cho nhà phát triển biết rằng có là một thay đổi đáng kể trong chữ ký của giao diện bên ngoài mà API hiển thị.

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

Ví dụ: bạn có thể gọi phương thức GET trên bản sửa đổi proxy API 1 để xem 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 thành phần cấu hình proxy API này được nêu chi tiết trong Tài liệu tham khảo về cấu hình proxy API.

Triển khai API cho một môi trường

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

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

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

Mọi tổ chức trong Apigee Edge đều có ít nhất 2 môi trường: test và prod. Chiến lược phát hành đĩa đơn bạn có thể tuỳ ý phân biệt. 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ở nó 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 tách riêng lưu lượng truy cập giữa Proxy API mà bạn đang xử lý và các proxy mà ứng dụng truy cập được trong thời gian chạy.

Môi trường cũng giúp 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 thử nghiệm và sản xuất mà chỉ có thể truy cập được bằng proxy API thực thi trong môi trường.

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 phiên bản triển khai

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. Một API proxy ở trạng thái triển khai có thể truy cập được 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 proxy API

Bạn không thể gọi proxy API cho đến khi triển khai. Dịch vụ API hiển thị API RESTful cung cấp khả năng kiểm soát quá trình triển khai.

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

Bạn đang xem tài liệu về Apigee Edge.
Tham khảo tài liệu về 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ố bản sửa đổi của proxy API 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 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 cho phương thức triển khai rồi đặt thành true.

Bạn không thể triển khai một bản sửa đổi của proxy API chồng lên một proxy API khác. Đầu tiên phải luôn là chưa 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 proxy API cần được triển khai trong bản sửa đổi hiện được triển khai. Kết quả là trình tự triển khai đảo ngược – bản sửa đổi mới được triển khai và sau khi triển khai hoàn tất, bản sửa đổi đã triển khai chưa được triển khai.

Ví dụ sau đây đặt giá trị override bằng cách truyền giá trị đó dưới dạng 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á hoạt động triển khai hơn nữa bằng cách đặt tham số delay. Chiến lược phát hành đĩa đơn Tham số delay chỉ định một khoảng thời gian, tính bằng giây, mà trước đó bản sửa đổi nên chưa được triển khai. Kết quả là các giao dịch đang diễn ra có một khoảng thời gian theo cần hoàn tất trước khi proxy API xử lý giao dịch của họ không được triển khai. Đang theo dõi điều gì sẽ xảy ra với override=true và tập hợp 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 đã gửi đến Bản sửa đổi 1.
  • Tuy nhiên, Bản sửa đổi 1 có thể vẫn đang xử lý các giao dịch hiện có. Bằng cách đặt delay (ví dụ: 15 giây), bạn cho Bản sửa đổi 1 15 giây để hoàn tất xử lý các giao dịch hiện có.
  • Sau khoảng thời gian trễ, Bản sửa đổi 1 sẽ không được 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 bình thường: bản sửa đổi hiện có chưa được triển khai, thì 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à mang lại sự liền mạch triển khai. Bản sửa đổi hiện có vẫn được triển khai trong khi bản sửa đổi mới cũng đang được triển khai đã triển khai. Khi bản sửa đổi mới được triển khai, bản sửa đổi cũ sẽ không được triển khai. Dùng trong kết hợp với tham số delay để kiểm soát thời điểm huỷ triển khai xảy ra.
delay

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

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

Khi dùng override=true cùng với delay, HTTP 5XX trong quá trình triển khai. Điều này là do cả hai bản sửa đổi proxy API sẽ được được triển khai đồng thời, với bản sửa đổi cũ hơn không được triển khai sau thời gian trì hoãn.

Xem tất cả các phiên bản triển khai API Bản sửa đổi

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

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 Cạnh. Bạn không thể thay đổi các chế độ cài đặt này trừ phi đang dùng ứng 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. Theo khi xem lại 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 proxy API đang được triển khai trong môi trường.

Xem tất cả các đợt 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ả bản sửa đổi số proxy API hiện đượ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 kiểm thử

Xem tất cả các đợt triển khai trong tổ chức

Để tìm nạp danh sách tất cả các bản sửa đổi hiện đã triển khai của tất cả proxy API trong mọi môi trường, 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ề cùng một kết quả như trên cho tất cả proxy API được triển khai trong tất cả 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 JSON hoặc XML với cùng một tài nguyên để tạo proxy API.

Một hồ sơ cho proxy API của bạn đã được tạo. Cách biểu thị mặc định của 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, tạo một proxy API có tên là weatherapi. Mô tả từng phần tử trong hồ sơ sau:

{
  "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 thể hiện cấu trúc đầy đủ của một API proxy:

  • APIProxy revision: Lặp lại được đánh số tuần tự của proxy API cấu hình, như được duy trì bởi các Dịch vụ API
  • APIProxy name: Tên riêng biệt của proxy API
  • ConfigurationVersion: Phiên bản Dịch vụ API mà proxy API là phiên bản cấu hình tuân thủ
  • CreatedAt: Thời gian proxy API được tạo, được định dạng theo thời gian UNIX
  • CreatedBy: Địa chỉ email của người dùng Apigee Edge đã tạo API proxy
  • DisplayName: Tên thân thiện với người dùng của proxy API
  • LastModifiedAt: Thời gian proxy API được tạo, có định dạng trong UNIX thời gian
  • LastModifiedBy: Địa chỉ email của người dùng Apigee Edge đã tạo API proxy
  • Policies: Danh sách các chính sách đã được thêm vào proxy API này
  • ProxyEndpoints: Danh sách các ProxyEndpoints được đặt tên
  • Resources: Danh sách các tài nguyên (JavaScript, Python, Java, ValueTrack) có sẵn để được thực thi trong proxy API này
  • TargetServers: Danh sách các TargetServers đã đặt tên (có thể được tạo bằng cách sử dụng Management API), đượ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 các TargetEndpoints đã đặt tên

Lưu ý rằng nhiều phần tử của cấu hình proxy API được tạo bằng cách sử dụng POST đơn giản ở trên không có dữ liệu. Trong các chủ đề sau, bạn sẽ tìm hiểu cách thêm và định cấu hình khoá của proxy API.

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

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

Phần Sử dụng proxy API mẫu, có trên GitHub cung cấp các tập lệnh shell gói công cụ triển khai Apigee. Nếu vì lý do nào đó 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 dưới đây.

Bao bọc công cụ triển khai

Trước tiên, hãy đảm bảo công cụ triển khai Python được có sẵn trong môi trường địa phương.

Sau đó, hãy tạo một tệp để lưu giữ thông tin xác thực của bạn. Các tập lệnh triển khai mà bạn viết sẽ nhập các cài đặt này, giúp bạn quản lý tập trung thông tin đăng nhập cho tài khoản của mình. Trong API Mẫu nền tảng, tệp này được gọi 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 cài đặt của bạn cho các tập lệnh shell bao bọc triển khai .

Bây giờ, hãy tạo một tập lệnh shell nhập các cài đặt đó và sử dụng chúng để gọi công cụ triển khai. (Để biết 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, bạn cũng nên 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}"

Gọi trực tiếp API

Bạn nên 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 proxy API.

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

#!/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