使用 API 部署 API Proxy

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

每個機構都有獨特的軟體開發生命週期 (SDLC)。通常必須同步及調整 API Proxy 部署作業，使其與後端服務所用的程序一致。

本主題中示範的 Edge API 方法可用於將 API Proxy 管理功能整合至貴機構的 SDLC。這個 API 的常見用途是編寫指令碼或程式碼，部署 API Proxy，或是將 API Proxy 從一個環境遷移至另一個環境，做為較大型自動化程序的一部分，該程序也會部署或遷移其他應用程式。

Edge API 不會對您的 SDLC (或任何人的 SDLC) 做出任何假設。 而是公開可由開發團隊協調的原子函式，以自動化及最佳化 API 開發生命週期。

如需完整資訊，請參閱「Edge API」。

如要使用 Edge API，您必須在呼叫中驗證身分。你可以透過下列任一方式執行此操作：

本主題著重於管理 API Proxy 的 API 集。

影片：觀看這部短片，瞭解如何部署 API。

與 API 互動

下列步驟將逐步說明如何與 API 進行簡單互動。

列出貴機構的 API

您可以先列出貴機構中的所有 API Proxy。(請記得替換 EMAIL:PASSWORD 和 ORG_NAME 的項目。如需相關操作說明，請參閱「使用 Edge API」一節。

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

回覆範例：

[ "weatherapi" ]

取得 API

您可以對機構中的任何 API Proxy 呼叫 GET 方法。這項呼叫會傳回 API Proxy 的所有可用修訂版本清單。

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

回覆範例：

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

這個方法只會傳回 API Proxy 的名稱，以及相關聯的修訂版本 (附帶相關聯的編號)。API Proxy 包含一組設定檔。修訂版本提供輕量機制，可讓您在疊代時管理設定更新。修訂版本會依序編號，因此您可以部署 API Proxy 的先前修訂版本，藉此還原變更。此外，您也可以將 API Proxy 的修訂版本部署至 prod 環境，同時繼續在 test 環境中建立該 API Proxy 的新修訂版本。準備就緒後，您可以從測試環境升級 API Proxy 的較新修訂版本，取代正式環境中先前的 API Proxy 修訂版本。

在本範例中，由於 API Proxy 剛建立，因此只有一個修訂版本。API Proxy 經過反覆設定和部署的生命週期時，修訂版本號碼會以整數遞增。使用直接 API 呼叫部署時，您可以選擇遞增 API Proxy 的修訂版本號碼。有時進行小幅變更時，您可能不想遞增修訂版本。

取得 API 修訂版本

API 版本 (例如 api.company.com/v1) 應很少變更。當您增加 API 版本號碼時，表示 API 公開的外部介面簽章有重大變更。

API Proxy 修訂版本是與 API Proxy 設定相關聯的遞增數字。API 服務會保留設定的修訂版本，因此發生錯誤時，您可以還原設定。根據預設，每次使用「匯入 API Proxy」API 匯入 API Proxy 時，API Proxy 的修訂版本都會自動遞增。如不想遞增 API Proxy 的修訂版本，請使用「更新 API Proxy 修訂版本」API。如果您使用 Maven 部署，請使用 clean 或 update 選項，詳情請參閱 Maven 外掛程式的 README。

舉例來說，您可以對 API Proxy 修訂版本 1 呼叫 GET 方法，取得詳細檢視畫面。

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

回應範例

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

API Proxy 設定參考資料中詳細說明瞭這些 API Proxy 設定元素。

將 API 部署至環境

設定 API Proxy，使其能正確接收及轉送要求後，您就可以將其部署至一或多個環境。通常您會在 test 中疊代 API Proxy，然後在準備就緒時，將 API Proxy 修訂版本升級至 prod。通常您會發現測試環境中的 API Proxy 修訂版本多出許多，主要是因為您在正式環境中進行的疊代次數較少。

API Proxy 必須先部署至環境，才能叫用。將 API Proxy 修訂版本部署至正式環境後，您就可以將 prod 網址發布給外部開發人員。

如何列出環境

Apigee Edge 中的每個機構至少有兩個環境：test 和 prod。這項區別是任意的。目標是提供一個區域，讓您在開放給外部開發人員使用前，先驗證 API Proxy 是否正常運作。

每個環境都只是網路位址，可讓您區隔正在處理的 API Proxy 與應用程式在執行階段存取的 API Proxy 之間的流量。

環境也會提供資料和資源的區隔。舉例來說，您可以在測試和正式環境中設定不同的快取，只有在該環境中執行的 API Proxy 才能存取。

查看機構中的環境

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

回應範例

[ "test", "prod" ]

探索部署項目

部署作業是指已部署至環境的 API Proxy 修訂版本。處於「已部署」狀態的 API Proxy 可透過網路存取，位址定義於該環境的 <VirtualHost> 元素中。

部署 API Proxy

API Proxy 必須先部署，才能叫用。API 服務會公開 RESTful API，可控管部署程序。

在特定時間，環境中只能部署一個 API Proxy 修訂版本。因此，您需要取消部署已部署的修訂版本。您可以控管新套件是否要部署為新修訂版本，或是覆寫現有修訂版本。

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

請先取消部署現有修訂版本。指定環境名稱和要取消部署的 API Proxy 修訂版本號碼：

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

然後部署新的修訂版本。API Proxy 的新修訂版本必須已存在：

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

順暢部署 (零停機)

如要盡量減少部署期間的停機時間，請在部署方法中使用 override 參數，並將其設為 true。

您無法在一個 API Proxy 修訂版本上部署另一個版本。第一個一律不得部署。將 override 設為 true，表示應部署 API Proxy 的一個修訂版本，取代目前部署的修訂版本。因此部署順序會反轉，也就是先部署新修訂版本，部署完成後再取消部署已部署的修訂版本。

以下範例會將 override 值做為表單參數傳遞，藉此設定該值： 

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

您可以設定 delay 參數，進一步最佳化部署作業。delay 參數會指定時間間隔 (以秒為單位)，在此時間間隔內，系統會取消部署先前的修訂版本。因此，API Proxy 處理交易前，進行中的交易會有時間間隔可完成。以下是 override=true 和 delay 參數集設定的行為：

  • 修訂版本 1 正在處理要求。
  • 修訂版本 2 正在平行部署。
  • 完全部署修訂版本 2 後，新流量會傳送至修訂版本 2。系統不會再將新流量傳送至修訂版本 1。
  • 不過，修訂版本 1 可能仍在處理現有交易。設定 delay 參數 (例如 15 秒) 後，系統會給修訂版本 1 15 秒的時間，完成現有交易的處理程序。
  • 延遲間隔結束後，系統會取消部署修訂版本 1。
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
查詢參數 說明
override

預設值為 false (正常部署行為：取消部署現有修訂版本，然後部署新修訂版本)。

設為 true 即可覆寫正常部署行為，並提供無縫部署。在部署新修訂版本時，現有修訂版本仍會繼續部署。部署新修訂版本時，系統會取消部署舊修訂版本。與 delay 參數搭配使用，可控管解除部署的時間。
delay

如要讓現有修訂版本在解除部署前完成交易處理，並避免發生 502 Bad Gateway 或 504 Gateway Timeout errors，請將這個參數設為您希望延遲解除部署的秒數。你可以設定的秒數沒有上限，設定較長的秒數也不會影響效能。延遲期間，系統不會將任何新流量傳送至舊版。

預設值為 0 秒。如果 override 設為 true 且 delay 為 0，系統會在部署新修訂版本後，立即取消部署現有修訂版本。負值會視為 0 秒。

搭配 delay 使用 override=true 時，可避免在部署期間出現 HTTP 5XX 回應。這是因為兩個 API Proxy 修訂版本會同時部署，舊版修訂版本會在延遲後解除部署。

查看 API 修訂版本的所有部署作業

有時需要擷取 API 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"
}

上述回應包含許多 Apigee Edge 內部基礎架構專用的屬性。除非您使用 Apigee Edge On-Premise，否則無法變更這些設定。

回應中包含的重要屬性為 organization、environment、aPIProxy、name 和 state。查看這些屬性值，即可確認 API Proxy 的特定修訂版本是否已部署至環境。

查看測試環境中的所有部署作業

您也可以使用下列呼叫，擷取特定環境的部署狀態 (包括目前部署的 API Proxy 修訂版本號碼)：

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

這會針對測試環境中部署的每個 API，傳回與上述相同的結果

查看貴機構的所有部署項目

如要擷取所有環境中所有 API Proxy 目前部署的所有修訂版本清單，請使用下列 API 方法：

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

這會傳回與上述相同的結果，適用於所有環境中部署的所有 API Proxy。

由於 API 符合 REST 樣式，您只要使用 POST 方法，搭配 JSON 或 XML 酬載，對相同資源執行操作，即可建立 API Proxy。

系統會產生 API Proxy 的設定檔，API Proxy 的預設表示法是 JavaScript 物件標記法 (JSON)。以下是上述 POST 要求的預設 JSON 回應，該要求建立名為 weatherapi 的 API Proxy。以下說明設定檔中的每個元素：

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

產生的 API Proxy 設定檔會顯示 API Proxy 的完整結構：

  • APIProxy revision：API 服務維護的 API Proxy 設定，以連續編號的疊代版本表示
  • APIProxy name：API Proxy 的專屬名稱
  • ConfigurationVersion：API Proxy 設定符合的 API 服務版本
  • CreatedAt：產生 API Proxy 的時間，格式為 UNIX 時間
  • CreatedBy：建立 API Proxy 的 Apigee Edge 使用者電子郵件地址
  • DisplayName：API Proxy 的易記名稱
  • LastModifiedAt：產生 API Proxy 的時間，格式為 UNIX 時間
  • LastModifiedBy：建立 API Proxy 的 Apigee Edge 使用者電子郵件地址
  • Policies：已新增至這個 API Proxy 的政策清單
  • ProxyEndpoints：具名 ProxyEndpoint 的清單
  • Resources：可在這個 API Proxy 中執行的資源清單 (JavaScript、Python、Java、XSLT)
  • TargetServers：具名 TargetServer 清單 (可使用管理 API 建立)，用於進階設定，以達到負載平衡目的
  • TargetEndpoints：具名 TargetEndpoint 的清單

請注意，使用上述簡單的 POST 方法建立的 API Proxy 設定，許多元素都是空白。在下列主題中，您將瞭解如何新增及設定 API Proxy 的主要元件。

您也可以參閱 API Proxy 設定參考資料，瞭解這些設定元素。

針對 API 編寫指令碼

GitHub 上的使用範例 API Proxy 提供包裝 Apigee 部署工具的 Shell 指令碼。如果基於某些原因無法使用 Python 部署工具，可以直接呼叫 API。下方範例指令碼會示範這兩種方法。

包裝部署工具

首先，請確認本機環境中已安裝 Python 部署工具。

接著建立檔案來存放憑證。您編寫的部署指令碼會匯入這些設定，協助您集中管理帳戶的憑證。在 API 平台範例中，這個檔案稱為 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

上述檔案會將所有設定提供給包裝部署工具的殼層指令碼。

現在請建立匯入這些設定的殼層指令碼，並使用這些設定呼叫部署工具。 (如需範例，請參閱 Apigee API 平台範例)。

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

為簡化工作流程，請一併建立指令碼來叫用及測試 API，如下所示：

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

直接叫用 API

編寫簡單的殼層指令碼，自動上傳及部署 API Proxy 的程序，會很有幫助。

下列指令碼會直接叫用 Management API。這項指令會取消部署您要更新的 API Proxy 現有修訂版本，從包含 Proxy 設定檔的 /apiproxy 目錄建立 ZIP 檔案，然後上傳、匯入及部署設定。

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