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 đều có một vòng đời phát triển phần mềm (SDLC) riêng. Thông thường, bạn cần đồng bộ hoá và điều chỉnh quy trình triển khai proxy API cho phù hợp với các quy trình dùng cho các dịch vụ phụ trợ.
Bạn có thể sử dụng các phương thức API Edge được trình bày trong chủ đề này để tích hợp tính năng quản lý proxy API vào SDLC của tổ chức. Cách sử dụng phổ biến của API này là viết các tập lệnh hoặc 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 quy trình tự động 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 về SDLC của bạn (hoặc của bất kỳ ai khác, đối với vấn đề đó). Thay vào đó, công cụ này hiển thị 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 để tự động hoá và tối ưu hoá vòng đời phát triển API.
Để biết thông tin đầy đủ, hãy xem phần API Edge.
Để sử dụng Edge API, bạn phải xác thực chính mình trong các cuộc 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 cộng)
- SAML (Đám mây công cộng và 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 bộ API được 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 thực hiện các 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. (Hãy nhớ thay thế các mục nhập cho EMAIL:PASSWORD và ORG_NAME. Để biết hướng dẫn, hãy xem phần Sử dụng API Edge.
curl -u EMAIL:PASSWORD \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis
Câu trả lời mẫu:
[ "weatherapi" ]
Tải API
Bạn có thể gọi phương thức GET trên bất kỳ proxy API nào trong tổ chức của mình. Lệnh gọi này trả về danh sách tất 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
Câu trả lời mẫu:
{
"name" : "weatherapi",
"revision" : [ "1" ]
}
Thông tin duy nhất mà phương thức này trả về là tên của proxy API cùng với bản sửa đổi liên quan (có số liên kết). Proxy API bao gồm một gói các tệp cấu hình. Bản sửa đổi cung cấp một cơ chế đơn giản để quản lý nội dung 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ỷ bỏ một thay đổi bằng cách triển khai một 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 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 proxy API trong môi trường thử nghiệm so với bản sửa đổi proxy API trước đó trong môi trường thực 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 di chuyển trong vòng đời của cấu hình và triển khai lặp lại, số bản sửa đổi sẽ tăng theo số nguyên. Khi sử dụng các lệnh gọi API trực tiếp để triển khai, bạn có thể tuỳ ý tăng số bản sửa đổi của proxy API. Đôi khi, thực hiện những thay đổi nhỏ, có thể bạn không muốn tăng giá trị sửa đổi.
Nhận bản sửa đổi API
Phiên bản API (ví dụ: api.company.com/v1) nên thay đổi rất ít khi. Khi bạn tăng phiên bản API, điều này cho các nhà phát triển biết rằng chữ ký của giao diện bên ngoài mà API hiển thị đã có thay đổi đáng kể.
Bản sửa đổi proxy API là một số tăng dần được liên kết với một cấu hình proxy API. Dịch vụ API duy trì các bản sửa đổi của cấu hình để bạn có thể huỷ bỏ cấu hình 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 API Nhập proxy API. Nếu bạn không muốn tăng số bản sửa đổi của proxy API, hãy sử dụng API Cập nhật bản sửa đổi proxy API. Nếu bạn đang sử dụng Maven để triển khai, hãy sử dụng các tuỳ chọn clean hoặc update, như mô tả trong 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 proxy API 1 để có chế độ 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
Câu trả lờ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 đề cập 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ủa bạn được định cấu hình để nhận và chuyển tiếp các yêu cầu đúng cách, bạn có thể triển khai proxy API cho 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 đó quảng bá bản sửa đổi proxy API lên prod khi đã sẵn sàng. Thông thường, bạn sẽ nhận thấy mình có nhiều bản sửa đổi hơn của proxy API trong môi trường kiểm thử, chủ yếu là do bạn sẽ thực hiện ít lặp lại hơn trong môi trường thực tế.
Không thể gọi proxy API cho đến khi proxy API đó được triển khai trong một môi trường. Sau khi triển khai bản sửa đổi proxy API cho phiên bản chính thức, 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 2 môi trường: test và prod. Sự khác 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 bình thường trước khi mở cho các nhà phát triển bên ngoài.
Mỗi môi trường thực ra chỉ là một địa chỉ mạng, cho phép bạn tách biệt lưu lượng truy cập giữa các proxy API mà bạn đang xử lý và những môi trường mà ứng dụng đang truy cập trong thời gian chạy.
Môi trường cũng cho phép phân tách dữ liệu và tài nguyên. Ví dụ: bạn có thể thiết lập nhiều bộ nhớ đệm trong môi trường thử nghiệm và chính thức. Chỉ các proxy API thực thi trong môi trường đó mới có thể truy cập vào những bộ nhớ đệm này.
Xem các môi trường trong 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á quy trình triển khai
Triển khai là 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 implementation (đã 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 proxy API
Không thể gọi proxy API cho đến khi triển khai xong. Dịch vụ API sẽ hiển thị các API RESTful giúp kiểm soát quá trình triển khai.
Tại mỗi thời điểm, bạn chỉ có thể triển khai một bản sửa đổi của proxy API trong một môi trường. Do đó, bản sửa đổi đã triển khai cần phải được gỡ bỏ. Bạn có thể kiểm soát việc gói mới sẽ được triển khai dưới dạng một bản sửa đổi mới hay ghi đè gó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 nguy cơ ngừng hoạt động trong quá trình triển khai, hãy sử dụng thông số override
trong phương thức triển khai và đặt thông số này thành true.
Bạn không thể triển khai bản sửa đổi này của proxy API lên trên một bản sửa đổi khác. Lựa chọn đầu tiên phải luôn không được triển khai. Khi đặt override thành true, bạn cho biết rằng một bản sửa đổi của proxy API sẽ được triển khai trên bản sửa đổi hiện đã đượ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ẽ không đượ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á quá trình triển khai hơn nữa 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 thời điểm mà bản sửa đổi trước đó không được triển khai. Kết quả là các giao dịch đang tiến hành có một khoảng thời gian để hoàn tất trước khi proxy API xử lý giao dịch của các giao dịch đó không được triển khai. Sau đây là những 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 chuyển đế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, Bản sửa đổi 1 vẫn có thể đang xử lý các giao dịch hiện tại. Khi đặt thông số
delay(ví dụ: 15 giây), bạn có 15 giây cho Bản sửa đổi 1 để 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ẽ 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 | Nội dung mô tả |
|---|---|
override |
Mặc định là Đặt thành |
delay |
Để cho phép hoàn tất quá trình xử lý giao dịch trên bản sửa đổi hiện có trước khi huỷ triển khai (và loại bỏ khả năng Giá trị mặc định là 0 (không) giây. Khi bạn đặt |
Khi sử dụng override=true cùng với delay, các phản hồi HTTP 5XX trong quá trình triển khai có thể bị loại bỏ. Điều này là do cả hai bản sửa đổi proxy API sẽ được triển khai đồng thời, trong khi bản sửa đổi cũ hơn không được triển khai sau độ trễ.
Xem tất cả quá trình triển khai 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 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 sẽ không thể thay đổi các chế độ cài đặt này trừ phi đ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 proxy API được triển khai trong một môi trường.
Xem tất cả phiên 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ố bản sửa đổi của 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ề cùng một kết quả 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 của bạn
Để tìm nạp danh sách tất 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, 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 đối với tất cả các proxy API được triển khai trong mọi môi trường.
Vì API 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 dựa trên cùng một tài nguyên để tạo proxy API.
Một hồ sơ cho proxy API của bạn sẽ được tạo. Giá trị biểu diễn mặc định của proxy API là ở dạng 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, phản hồi này đã tạo một proxy API có tên weatherapi. Nội dung mô tả về từng phần tử trong hồ sơ như 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 minh hoạ cấu trúc đầy đủ của một proxy API:
APIProxy revision: Vòng lặp đượ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 APIConfigurationVersion: Phiên bản Dịch vụ API mà cấu hình proxy API tuân theoCreatedAt: Thời gian proxy API được tạo, được định dạng theo thời gian UNIXCreatedBy: Địa chỉ email của người dùng Apigee Edge đã tạo proxy APIDisplayName: Tên thân thiện với người dùng cho proxy APILastModifiedAt: Thời điểm proxy API được tạo, được định dạng theo thời gian UNIXLastModifiedBy: Địa chỉ email của người dùng Apigee Edge đã tạo proxy APIPolicies: Danh sách các chính sách đã được thêm vào proxy API nàyProxyEndpoints: Danh sách ProxyEndpoints có tênResources: Danh sách các tài nguyên (JavaScript, Python, Java, GCC) có sẵn để thực thi trong proxy API nàyTargetServers: Danh sách các TargetServers có tên (có thể tạo bằng API quản lý), dùng trong các cấu hình nâng cao nhằm mục đích cân bằng tảiTargetEndpoints: Danh sách TargetEndpoints đã đặt tên
Xin lưu ý rằng nhiều phần tử của cấu hình proxy API được tạo bằng phương thức POST đơn giản ở trên bị 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 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.
Viết tập lệnh dựa trên API
Phần Sử dụng 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 này. Bạn có thể xem cả hai phương pháp trong các tập lệnh mẫu dưới đây.
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 đó, tạo một tệp để lưu giữ 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ý tập trung thông tin xác thực cho tài khoản của mình. Trong mẫu Nền tảng API, 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 chế độ cài đặt của bạn cho các tập lệnh shell gói công cụ triển khai.
Bây giờ, hãy tạo 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. (Để tham khảo ví dụ, hãy xem 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}"
Gọi API trực tiếp
Bạn nên viết các tập lệnh shell đơn giản giúp tự động hoá quy trình tải lên và triển khai proxy API.
Tập lệnh bên dưới trực tiếp gọi API quản lý. Trình này sẽ huỷ 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 các tệp cấu hình proxy, 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