在 Apigee 環境中部署及管理封存檔案

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

預先發布版 — Archive deployment

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

使用 VS Code 中的 Apigee 開發及測試程式化的 API Proxy。 然後，按照下列章節所述，將 API Proxy 設定環境的封存檔部署至 Apigee 整合測試和實際工作環境。

注意：如要將封存檔案部署至 Apigee 環境，您必須是機構管理員。如要查看封存的部署作業，您必須是機構管理員或唯讀管理員。詳情請參閱「Apigee 角色」。

在 Apigee 環境中啟用封存檔案部署作業

如要部署封存檔案，您必須先在 Apigee 環境中啟用封存檔案部署作業。

注意：請先詳閱下列封存部署資訊，再繼續操作：

• Apigee 環境的名稱必須與本機開發環境的名稱相符。
• 在環境中啟用封存部署作業後，為避免與本機開發作業發生衝突，您將無法使用 Apigee 使用者介面、API 或 gcloud，在環境中執行部分動作。詳情請參閱「封存部署作業可防止執行的動作摘要」。
• 建立環境後，就無法變更部署類型。
• 如要使用佈建精靈建立環境 (如「建立環境和環境群組」一文所述)，無法選取封存做為環境的部署類型。
• 您必須是機構管理員，才能建立環境。

按照下列各節的說明啟用封存部署作業。

傳統版 Apigee UI

如要在 Apigee 環境中啟用封存檔案部署功能，請建立 Apigee 環境 (在佈建精靈之外)，然後選取「部署類型」下方的「封存檔案」。

Apigee API

如要在使用 API 建立環境時啟用封存部署作業，請在要求內文中將 deploymentType 設為 ARCHIVE。

例如：

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments" \
   -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-type: application/json" \
   -d
   '{
      "name": "integration-test",
      "description": "Integration test environment",
      "displayName" : "Integration test",
      "deploymentType" : "ARCHIVE"
   }'

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解所用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

以下是回應範例：

{
  "name": "organizations/$ORG/operations/11b1ad1c-2371-473d-bcd4-f621f8d98ef7",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/$ORG/environments/integration-test",
    "state": "IN_PROGRESS"
  }
}

您可以查看作業狀態。例如：

curl https://apigee.googleapis.com/v1/organizations/$ORG/operations/11b1ad1c-2371-473d-bcd4-f621f8d98ef7 /
   -H "Authorization: Bearer $TOKEN"

以下是回應範例。請注意，作業的狀態為 FINISHED，環境的狀態則設為 ACTIVE。

{
  "name": "organizations/$ORG/operations/11b1ad1c-2371-473d-bcd4-f621f8d98ef7",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/$ORG/environments/integration-test",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.Environment",
    "name": "integration-test",
    "description": "Integration test environment",
    "createdAt": "1615553880084",
    "lastModifiedAt": "1615553881911",
    "displayName": "Integration test",
    "state": "ACTIVE",
    "deploymentType": "ARCHIVE"
  }
}

如要進一步瞭解 API，請參閱「建立環境 API」。

將封存檔案部署至 Apigee 環境

注意：

• 如要將封存檔案部署至環境，必須啟用封存檔案部署功能。
• Apigee 環境中先前部署的封存檔案，Apigee 最多只會保留 50 個。
• 目前未部署的部署作業封存修訂版本將在 30 天後刪除。
• 您無法使用 Apigee UI 查看或管理封存的部署作業。如需更多資訊和解決方法，請參閱 VS Code 中 Apigee 的已知問題。

如要將封存檔案部署至 Apigee 環境，請使用下列 gcloud 指令：

gcloud beta apigee archives deploy \
    --environment=$ENV \
    [--organization=$ORG] \
    [--source=$SOURCE] \
    [--labels $KEY=$VALUE[,$KEY2=$VALUE2,$KEY3=$VALUE3,...]]

您必須使用 --environment 標記，指定要部署封存檔的 Apigee 環境。Apigee 環境必須啟用封存檔案部署功能。 詳情請參閱 gcloud beta apigee archives deploy。

根據預設，系統會部署封存檔：

• 與為 gcloud 設定的目前有效專案相關聯的機構。

  如要查看目前的 gcloud 設定，請執行 gcloud config list。如要指定機構，請使用 --organization 標記。

• 從目前的工作目錄。
  如果封存檔的 src/main/apigee 根目錄不在目前的工作目錄中，請使用 --source 旗標指定封存檔根目錄的位置。另請參閱「瞭解 Apigee 工作區的結構」。
注意：如果您先前已將封存檔部署至 Apigee 環境，系統會重新部署所有 API Proxy 並建立新修訂版本，無論封存檔中包含哪些變更。

您也可以使用 --labels 旗標，在封存部署作業中新增最多 64 個自訂標籤鍵/值組合。舉例來說，您可能會想為封存檔加上版本號碼標籤。列出封存部署項目時，系統會顯示標籤。鍵值必須符合下列規範：

• 長度上限為 63 個半形字元
• 大小上限為 128 個位元組
• 採用 UTF-8 編碼
• 符合下列與 Perl 相容的規則運算式 (PCRE)： [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62}

在 Google Cloud 上部署至 Apigee 時，gcloud 指令會在幕後執行下列步驟：

1. 建立 src/main/apigee Apigee 工作區目錄的 ZIP 檔案。詳情請參閱「瞭解 Apigee 工作區的結構」。
   注意：建立 ZIP 檔案時，系統只會納入 src/main/apigee 目錄中具有下列副檔名的檔案類型： .jar、.java、.js、.jsc、.json、.properties、.py、.wsdl、.xml、.xsd

   如果檔案沒有上述副檔名，系統會將其排除在 ZIP 檔案之外。

2. 將封存檔部署至 Google Cloud 上的 Apigee，步驟如下：
   1. 使用 generateUploadUrl API，為與目前 Apigee 機構相關聯的專案中的 Google Cloud Storage bucket 產生已簽署網址。
   2. 使用已簽署的網址，將封存 ZIP 檔案上傳至 Cloud Storage bucket。
   3. 將目前在 Cloud Storage 值區中暫存的封存檔部署至 Google Cloud 上的 Apigee。使用 Archive Deployments API。

要求範例

以下範例會在目前目錄中建立 src/main/apigee 的 zip 封存檔，並將其部署至指定的 Apigee 環境：

gcloud beta apigee archives deploy --environment=$ENV

以下範例說明如何指定與為 gcloud 設定的目前有效專案無關的機構：

gcloud beta apigee archives deploy --environment=$ENV --organization=$ORG

以下範例會在 myarchive 下建立 src/main/apigee 目錄的 zip 封存檔，並將其部署至指定的 Apigee 環境：

gcloud beta apigee archives deploy --environment=$ENV --source=/myarchive

以下範例會將 status 和 build_id 標籤新增至封存部署作業：

gcloud beta apigee archives deploy --environment=$ENV --labels=status=released,build=210315

回覆範例

以下是回應範例：

Using Apigee organization 'myorg'
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.

查看封存部署狀態

如要檢查封存部署作業狀態，請使用 gcloud alpha apigee operations 指令。

以下範例顯示修訂版本 ID 為 439fa3f7-6aa4-42ad-8b12-3ca912c75d5c 的作業，其封存部署狀態為 IN_PROGRESS。

gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

以下是回應範例。請注意，state 會設為 IN_PROGRESS。

Using Apigee organization 'myorg'
done: true
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: IN_PROGRESS
  targetResourceName: uri
name: organizations/myorg/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed
organization: myorg
response:
  '@type': type.googleapis.com/google.cloud.apigee.v1.CanaryEvaluation
  control: 1-5-0-20210319-071117-ghq74
  endTime: '2021-03-20T06:15:44.329363950Z'
  metricLabels:
    env: test
    location: us-central1
  name: uri
  startTime: '2021-03-20T06:14:44.306534584Z'
  treatment: 1-5-0-20210319-190954-if0wk
  verdict: NONE
uuid: b64c2665-b5ac-43cc-9e2d-232e8895c2ed

作業完成後，state 會設為 FINISHED。

列出環境中的所有封存部署作業

按照下列各節所述，列出環境中的所有封存部署作業。

注意：以封存部署方式部署的 API Proxy 和共用流程不會顯示在 API Proxy 清單中。

gcloud

如要列出 Google Cloud 上 Apigee 中的所有封存部署作業，請使用下列 gcloud 指令：

gcloud beta apigee archives list --environment=$ENV

您必須使用 --environment 標記，指定要查看封存部署項目的 Apigee 環境。 Apigee 環境必須查看封存部署作業的詳細資料。 詳情請參閱 gcloud beta apigee archives list。

以下是回應範例：

Using Apigee organization 'myorg'
ARCHIVE ID                        ENVIRONMENT   DEPLOYED AT           LABELS                         OPERATION STATUS
pzfbs8uidbdv224joz                myorg         2021-03-10 11:21:29   status=released,build=210315   Deployed
fb4r8log2gm63r3gtu                myorg         2021-03-05 13:40:30
vrytwbhso558oil53m                myorg         2021-03-03 21:20:53

Apigee API

如要列出環境中的封存部署作業，請對下列 API 發出 GET 要求： https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments。

例如：

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments" \
  -H "Authorization: Bearer $TOKEN"

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解所用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

以下是回應範例：

{
  "archiveDeployments": [
    {
      "name": "organizations/myorg/environments/integration-test/archiveDeployments/pzfbs8uidbdv224joz",
      "labels": {
        "status": "released",
        "build": "210315"
      },
      "createdAt": "1615821232451727",
      "updatedAt": "1615821232451727",
      "operation": "organizations/apigee-docs-c/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed"
    },
    {
      "name": "organizations/myorg/environments/integration-test/archiveDeployments/fb4r8log2gm63r3gtu",
      "createdAt": "1615819281858447",
      "updatedAt": "1615819281858447",
      "operation": "organizations/apigee-docs-c/operations/71549b9c-4493-41b6-9838-c0ad5b1b3181"
    },
    {
      "name": "organizations/myorg/environments/integration-test/archiveDeployments/vrytwbhso558oil53m",
      "createdAt": "1615578337832207",
      "updatedAt": "1615578337832207",
      "operation": "organizations/apigee-docs-c/operations/a2eb50b5-f276-4de4-96a3-72fac3d4c05e"
    }
  ]
}

查看封存部署作業的詳細資料

如要查看封存部署作業的詳細資料，請參閱下列章節。

gcloud

如要在 Google Cloud 上的 Apigee 中查看封存部署作業的詳細資料，請使用下列 gcloud 指令：

gcloud beta apigee archives describe $ID --environment=$ENV

您必須指定下列項目：

• 封存部署版本的 ID。
• 您要使用 --environment 旗標查看封存部署項目的 Apigee 環境。 Apigee 環境必須啟用封存檔案部署作業。

詳情請參閱 gcloud beta apigee archives describe。

例如：

gcloud apigee archives describe pzfbs8uidbdv224joz --environment=$ENV

以下是回應範例：

Using Apigee organization 'myorg'
createdAt: '1615578337832207'
labels:
  status: 'released'
  build: '210315'
name: organizations/myorg/environments/$ENV/archiveDeployments/pzfbs8uidbdv224joz
operation: organizations/myorg/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed
operationStatus: Deployed
updatedAt: '1615821232451727'

Apigee API

如要查看封存部署作業的詳細資料，請對下列 API 發出 GET 要求： https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID。

您必須傳遞封存部署修訂版本的 ID。如要查看 Apigee 環境的封存部署修訂版本 ID 清單，請參閱「列出環境中的所有封存部署作業」。

例如：

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/pzfbs8uidbdv224joz" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解所用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

以下是回應範例：

{
  "name": "organizations/myorg/environments/integration-test/archiveDeployments/pzfbs8uidbdv224joz",
  "labels": {
     "status": "released",
     "build": "210315"
  },
  "createdAt": "1615578337832207",
  "updatedAt": "1615821232451727",
  "operation": "organizations/apigee-docs-c/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed"
}

更新封存部署的標籤

請按照下列各節所述，更新封存部署作業的標籤。

gcloud

如要更新 Google Cloud 上 Apigee 封存部署項目的標籤，請使用下列 gcloud 指令：

gcloud beta apigee archives update [$ID] --environment=$ENV
  [--update-labels=$KEY=$VALUE[,$KEY2=$VALUE2...$KEYn=$VALUEn]],
  [--clear-labels | --remove-labels=$KEY[,$KEY2...$KEYn]]

您必須指定下列項目：

• 封存部署作業修訂版本的 ID
• 您要使用 --environment 旗標查看封存部署項目的 Apigee 環境。 Apigee 環境必須啟用封存檔案部署功能。
• 下列一或多個旗標：

  旗標	說明
  --clear-labels	移除所有標籤。如果也指定了 --update-labels，系統會先套用 --clear-labels。 如果已指定 --remove-labels，則無法指定這個選項。
  --remove-labels	移除指定標籤。如果也指定了 --update-labels，系統會先套用該值。 如果已指定 --clear-labels，則無法指定這個選項。
  --update-labels	更新標籤。如果標籤存在，系統會修改其值；否則會建立新標籤。如要移除部分或所有標籤，請分別搭配使用 --remove-labels 或 --clear-labels 旗標，再更新標籤。

  注意： $KEY 開頭須為小寫字元，且只能包含連字號 (-)、底線 (_)、小寫字元和數字。$VALUE只能包含連字號 (-)、底線 (_)、小寫字元和數字。

詳情請參閱 gcloud beta apigee archives update。

例如：

gcloud apigee archives update pzfbs8uidbdv224joz --environment=$ENV \
  --clear-labels --update-labels=status=released,build=210315,tier=1

以下是回應範例：

Using Apigee organization `myorg`
createdAt: 2020-04-04T04:04:04.004Z
labels:
  status: released,
  build: 210315,
  tier: 1
name: organizations/apigee-docs-c/environments/dev/archiveDeployments/pzfbs8uidbdv224joz
operation: organizations/apigee-docs-c/operations/bf587121-8b5c-4897-9d8f-9b1ef0cb06ca
updatedAt: '1633450432067431'

Apigee API

如要在 Google Cloud 的 Apigee 中更新封存部署作業的標籤，請對下列 API 發出 PATCH 要求： https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID。

您必須傳遞封存部署修訂版本的 ID。如要查看 Apigee 環境的封存部署修訂版本 ID 清單，請參閱「列出環境中的所有封存部署作業」。

在要求主體中，傳遞要新增至封存的所有標籤。您傳遞的標籤會覆寫目前的標籤組合，因此您可以從要求主體中省略標籤來移除標籤，或傳遞空白清單來移除所有標籤。

例如：

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID" \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "labels": {
      "status" : "released",
      "build" : "210315"
    }
  }'

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解所用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

以下是回應範例：

{
  "name": "organizations/myorg/environments/integration-test/archiveDeployments/pzfbs8uidbdv224joz",
  "labels": {
     "status": "released",
     "build": "210315"
  },
  "createdAt": "1615578337832207",
  "updatedAt": "1615821232451727",
  "operation": "organizations/apigee-docs-c/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed"
}

刪除含有封存部署作業的 Apigee 環境

注意：在這個版本中，您無法從 Apigee 環境取消部署封存檔，因此必須先取消部署，才能刪除環境。如要刪除 Apigee 環境，請先部署未定義任何部署作業的封存檔，然後再刪除 Apigee 環境，如本節所述。

如要刪除含有封存部署作業的 Apigee 環境，請按照下列步驟操作：

1. 在臨時資料夾中建立下列目錄結構，其中 $ENV 與要刪除的環境名稱相符。 例如：

   mkdir -p /$TEMP/archive/src/main/apigee/environments/$ENV

2. 將 deployments.json 檔案新增至目錄。例如：

   touch /$TEMP/archive/src/main/apigee/environments/$ENV/deployments.json

3. 更新 deployments.json，加入空白的 proxies 陣列，如下所示。

   {
   "proxies" : []
   }

4. 將目錄 (cd) 變更為 $TEMP/archive 資料夾。

   cd $TEMP/archive

   如果

5. 將封存檔案部署至要刪除的 Apigee 環境。

   gcloud beta apigee archives deploy --environment=$ENV
   

6. 刪除 Apigee 環境。

刪除封存部署作業的修訂版本

按照下一節說明，刪除封存部署作業的修訂版本。

注意：您無法刪除目前部署的封存部署項目修訂版本。如要瞭解如何查看封存部署修訂版本的部署狀態，請參閱「列出環境中的所有封存部署」。如要刪除目前已部署的封存部署作業修訂版本，請刪除環境。

gcloud

如要刪除 Google Cloud 上 Apigee 中封存部署項目的修訂版本，請使用下列 gcloud 指令：

gcloud beta apigee archives delete $ID --environment=$ENV

您必須指定下列項目：

• 要刪除的修訂版本 ID。
• 您要使用 --environment 旗標查看封存部署項目的 Apigee 環境。 Apigee 環境必須啟用封存檔案部署功能。

例如：

gcloud apigee archives delete fb4r8log2gm63r3gtu --environment=dev

以下是回應範例：

Archive deployment revision "fb4r8log2gm63r3gtu" deleted

Apigee API

如要刪除 Google Cloud 上 Apigee 封存部署項目的修訂版本，請對下列 API 發出 DELETE 要求： https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID。

您必須傳遞要刪除的封存部署修訂版本 ID。如要查看環境的封存部署修訂版本 ID 清單，請參閱「列出環境中的所有封存部署作業」。

例如：

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN" \

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解所用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

以下是回應範例：

{}