使用 API 部署 API Proxy

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

每個機構都有獨特的軟體開發生命週期 (SDLC)。通常需要將 API Proxy 部署作業與用於後端服務的程序同步處理並保持一致。

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

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

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

如要使用 Edge API，您必須在呼叫中驗證身分。您可以選擇下列其中一種方法：

  • OAuth2 (僅限公有雲)
  • SAML (公開和私人雲端)
  • 基本驗證 (不建議使用；公有雲和私有雲)

本主題著重介紹用於管理 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 的修訂版本部署至正式環境，同時在測試環境中繼續建立該 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 服務會維護您的設定修訂版本，讓您在發生問題時可以還原設定。根據預設，每次使用 Import an API Proxy API 匯入 API Proxy 時，API Proxy 的修訂版本就會自動遞增。如果您不想增加 API Proxy 的修訂版本，請使用 Update API Proxy 修訂版本 API。如果您要使用 Maven 進行部署，請按照 Maven 外掛程式 README 的說明使用 clean 或 update 選項。

舉例來說，您可以針對 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 以正確接收及轉送要求後，您就能將 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 才能存取。

查看機構中的環境

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 服務公開符合 REST 樣式的 API，可用於控管部署程序。

一個環境一次只能部署一個 API Proxy 的修訂版本。因此，您必須取消部署已部署的修訂版本。您可以控制要將新的套裝組合部署為新的修訂版本，還是會覆寫現有的修訂版本。

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊

請先取消部署現有的修訂版本。指定要取消部署的環境名稱和 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 修訂版本上方部署一個 API Proxy 修訂版本。前者一律必須取消部署。將 override 設為 true，即表示應透過目前部署的修訂版本部署 API Proxy 的一個修訂版本。結果是部署作業序列反轉，新的修訂版本會部署完成，並在部署作業完成後取消部署已部署的修訂版本。

以下範例會將 override 值做為表單參數傳遞，藉此設定 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 (零) 秒。

在 override=true 與 delay 搭配使用時，可以刪除部署期間的 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 地端部署系統，就無法變更這些設定。

回應中包含的重要屬性包括 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：具名 TargetServers 清單 (可透過 Management API 建立)，可在進階設定中使用，用於負載平衡
  • TargetEndpoints：已命名的 TargetEndpoint 清單

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

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

針對 API 編寫指令碼

GitHub 上的使用範例 API Proxy 提供包裝 Apigee 部署工具的殼層指令碼。如果因故無法使用 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