Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定及移除自訂中繼資料

Linux Windows

每個中繼資料項目都會以鍵/值組合的形式儲存在中繼資料伺服器上。中繼資料鍵會區分大小寫。鍵可以是預先定義或自訂的中繼資料鍵。

自訂中繼資料可讓您在個別 VM 或專案中，建立及使用自己的中繼資料鍵/值組合。您可以新增自訂中繼資料鍵、更新現有鍵的值，以及移除不需要的自訂中繼資料項目。設定自訂中繼資料，有助於將任意值傳遞至專案中的 VM。這項功能也可用於建立啟動和關閉指令碼。

本文說明如何執行下列操作：

新增或更新 VM 的自訂中繼資料
從 VM 移除自訂中繼資料

事前準備

請先瞭解 Compute Engine VM 中繼資料的定義、分類和排列方式。詳情請參閱「關於 VM 中繼資料」。

如果尚未設定驗證，請先完成設定。驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：
選取這個頁面上範例的預計用途分頁：
控制台

使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，您不需要設定驗證機制。
gcloud
1. 安裝 Google Cloud CLI。完成後，執行下列指令來初始化 Google Cloud CLI：
  gcloud init
  如果您使用外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
  
  注意：如果您已經安裝 gcloud CLI，請務必執行 gcloud components update，確認您安裝的是最新版本。
設定預設區域和可用區。

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

安裝 Google Cloud CLI。

如果您使用外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

必要的角色

如要取得在 VM 上設定或移除自訂中繼資料所需的權限，請要求管理員授予您下列 IAM 角色：

Compute 執行個體管理員 (v1) (roles/compute.instanceAdmin.v1) 在 VM 或專案上
如果 VM 使用服務帳戶：服務帳戶或專案的服務帳戶使用者 (roles/iam.serviceAccountUser)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備在 VM 上設定或移除自訂中繼資料所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要在 VM 上設定或移除自訂中繼資料，必須具備下列權限：

如果 VM 使用服務帳戶： iam.serviceAccounts.actAs 服務帳戶或專案
如要新增、更新或移除自訂專案中繼資料：
- 專案有 compute.projects.get
- 專案的 compute.projects.setCommonInstanceMetadata
如要新增、更新或移除自訂可用區中繼資料，請按照下列步驟操作：
- compute.instanceSettings.get 專案中所需區域的執行個體設定
- compute.instanceSettings.update 專案中所需區域的執行個體設定
如要新增、更新或移除自訂執行個體中繼資料，請按照下列步驟操作：
- VM 上的 compute.instances.get
- compute.instances.setMetadata 在 VM 上

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

限制

VM 中繼資料項目有下列限制。

大小限制

Compute Engine 規定所有中繼資料項目的總大小上限為 512 KB。每個 key 和 value 也會套用大小上限，如下所示：

每個中繼資料 key 的大小上限為 128 個位元組。
每個中繼資料 value 的大小上限為 256 KB。

舉例來說，安全殼層金鑰會以自訂中繼資料的形式儲存在 ssh-keys 鍵底下。如果這個金鑰的中繼資料內容或 value 超過 256 KB 的限制，您就無法新增更多安全殼層金鑰。如果達到這項限制，請考慮移除未使用的金鑰，釋出中繼資料空間來儲存新金鑰。

此外，如果您直接提供啟動或關機指令碼內容，這些啟動和關機指令碼內容也可能會儲存為自訂中繼資料，並計入這些大小限制。如要避免發生這種情況，請將開機或關機指令碼儲存為託管於外部位置 (例如 Cloud Storage) 的檔案，並在建立 VM 時提供開機指令碼網址。這樣一來，這些檔案就會下載到 VM，而不是儲存在中繼資料伺服器。

字串大小寫限制

每個中繼資料 key 都會區分大小寫。
除了布林值以外，每個中繼資料 value 都會區分大小寫。

可用區中繼資料限制

您只能使用 gcloud CLI 或 REST 設定及移除區域中繼資料。
即使索引鍵的大小寫不同，您也無法使用相同字串建立兩個不同的中繼資料鍵。舉例來說，如果特定區域的區域中繼資料已有名為 zonal-metadata-key 的自訂中繼資料鍵，您就無法建立與該字串類似的新區域中繼資料鍵，例如 Zonal-Metadata-Key 或 ZONAL-METADATA-KEY。
您無法為安全殼層金鑰設定可用區中繼資料值，這些金鑰會以自訂中繼資料的形式儲存在 ssh-keys 鍵下。

布林值

對於接受布林值 TRUE 或 FALSE 的欄位，也可以使用下列值：

狀態	替代值
`TRUE`	`Y`、`Yes`、`1`
`FALSE`	`N`、`No`、`0`

布林值不區分大小寫。舉例來說，你可以使用 False、false 或 FALSE 停用某項功能。

設定 VM 的自訂中繼資料

本節說明如何透過下列方式，為 Compute Engine VM 新增自訂中繼資料，或更新現有自訂中繼資料值：

設定自訂專案中繼資料，為專案中的所有 VM 新增或更新自訂專案中繼資料。
設定自訂可用區中繼資料，為專案中的 VM 新增或更新可用區範圍的自訂中繼資料。
設定自訂執行個體中繼資料，為特定 VM 新增或更新自訂執行個體中繼資料。

設定自訂專案中繼資料

如要為專案中的所有執行個體新增或更新自訂中繼資料，可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST。

按照這些指示，將中繼資料設定套用至專案中的所有 VM。舉例來說，如果您定義專案中繼資料配對 baz=bat，該中繼資料配對就會自動套用至專案中的所有 VM。

控制台

前往 Google Cloud 控制台的「Metadata」頁面。
前往「自訂中繼資料」頁面
按一下頁面頂端的「編輯」。
如要新增自訂專案中繼資料項目，請按照下列步驟操作：
1. 前往頁面底部，然後按一下「Add item」(新增項目)。
2. 在「Key」(鍵) 欄位中，輸入自訂中繼資料鍵的名稱。
3. 在「Value」(值) 欄位中，輸入自訂專案中繼資料值。
4. 選用。如要新增更多自訂專案中繼資料項目，請針對要新增的每個中繼資料項目重複上述步驟。
5. 如要完成新增自訂專案中繼資料項目，請按一下「儲存」。
如要編輯現有的自訂專案中繼資料項目，請按照下列步驟操作：
1. 找到要編輯的中繼資料項目。
2. 如要更新特定自訂中繼資料鍵的名稱，請在該項目的「鍵」欄位中輸入新名稱。
3. 如要更新自訂專案中繼資料項目的值，請在該項目的「Value」(值) 欄位中輸入新值。
4. 選用。如要移除特定自訂專案中繼資料項目，請點按中繼資料項目旁的刪除圖示。
5. 如要編輯多個自訂專案中繼資料項目，請針對要編輯的每個中繼資料項目重複上述步驟。
6. 如要完成編輯自訂專案中繼資料項目，請按一下「儲存」。

gcloud

使用 project-info add-metadata 指令。

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

更改下列內容：

KEY：中繼資料鍵名稱
VALUE：這個鍵儲存的值

範例

舉例來說，如要在專案中設定兩個新項目 foo=bar 和 baz=bat，請執行下列指令：

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

您可以選擇使用 --metadata-from-file 旗標，指定一或多個要讀取中繼資料的檔案。

REST

選用。如要執行樂觀鎖定，可以提供指紋。

指紋是由 Compute Engine 產生的隨機字元字串。每次要求後，指紋都會變更，如果提供的指紋不符，系統會拒絕要求。

如果未提供指紋，系統不會執行一致性檢查，projects().setCommonInstanceMetadata 要求也會成功。這與 instances().setMetadata 和 instanceSettings().patch 方法不同，後者一律需要指紋。

如要取得專案目前的指紋，請呼叫 project().get 方法。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
```
輸出結果會與下列內容相似：
```
{
  "name": "myproject",
  "commonInstanceMetadata": {
    "kind": "compute#metadata",
    "fingerprint": "FikclA7UBC0=",
    ...
  }
}
```

向 projects().setCommonInstanceMetadata 方法提出要求，並設定自訂中繼資料鍵/值組合：

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
  "fingerprint": "FikclA7UBC0=",
  "items": [
    {
    "key": "foo",
    "value": "bar"
    }
  ]
}

將 PROJECT_ID 替換為專案 ID。

設定自訂可用區中繼資料

設定自訂可用區中繼資料時，您會為專案中特定可用區內的 VM 新增或更新可用區中繼資料項目。您可以透過設定自訂區域中繼資料執行下列操作：

為專案中的特定可用區建立新的自訂中繼資料鍵，並為該專案中該可用區的所有 VM 設定中繼資料。
更新專案中特定可用區內所有 VM 的現有自訂可用區中繼資料項目值。
對於具有專案中繼資料值的現有自訂中繼資料鍵，請在特定可用區中覆寫這些專案中繼資料值，並改為設定可用區中繼資料。在特定可用區中為這些鍵設定可用區中繼資料後，該專案中該可用區的所有 VM 都會使用這些鍵的可用區中繼資料值。

設定自訂可用區中繼資料前的注意事項

專案和區域中繼資料項目會儲存在同一個 project/ 目錄中。如果您在專案層級和可用區層級，為 VM 設定相同自訂中繼資料鍵的不同值，則這些鍵的可用區中繼資料值，會優先於相應可用區中的專案中繼資料值。

如果為已具有專案中繼資料值的金鑰新增可用區中繼資料值，Compute Engine 會覆寫指定可用區中 VM 的專案中繼資料值，並使用可用區值更新 /project 目錄。
如果為已具有區域中繼資料值的金鑰新增專案中繼資料值，則不會有任何變更。Compute Engine 會將區域中繼資料值保留在特定區域的 /project 目錄中。
如果您未在特定可用區中，為自訂中繼資料鍵指定可用區中繼資料值，但該鍵具有專案中繼資料值，則 VM 在這些可用區中仍會具有專案中繼資料值。

程序

您可以使用 Google Cloud CLI 或 REST，在專案的特定可用區中新增或更新自訂可用區中繼資料。

gcloud

如要新增或更新自訂可用區中繼資料，請使用 gcloud compute project-zonal-metadata add 指令。
```
gcloud compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...
```
更改下列內容：
- PROJECT_ID：專案 ID
- ZONE：要新增或更新可用區中繼資料的可用區。
- KEY1、KEY2...：要新增或更新區域中繼資料值的自訂中繼資料鍵。
- VALUE1、VALUE2...：要為現有和新的自訂中繼資料鍵設定的區域中繼資料值。視自訂中繼資料鍵和值而定，會發生下列其中一種情況：
- 如果對應的自訂中繼資料鍵是具有專案中繼資料的現有鍵，則在指定區域中，Compute Engine 會以您指定的區域中繼資料值，覆寫該鍵的專案中繼資料值。專案中指定可用區的所有 VM 都會沿用該鍵的新指定可用區中繼資料，其他可用區的 VM 則會繼續保留其現有的專案或可用區中繼資料值。如果日後更新這個鍵的專案中繼資料值，專案中這個可用區內的 VM 仍不受影響，並繼續使用這個鍵的可用區中繼資料值。
- 如果對應的自訂中繼資料鍵是新的中繼資料鍵，且未用於現有專案或可用區中繼資料，則 Compute Engine 會建立自訂中繼資料鍵，並將這個值設為指定可用區中的可用區中繼資料。
- 如果相應的自訂中繼資料鍵是現有的中繼資料鍵，且在指定可用區中具有可用區中繼資料值：
  - 如果指定的中繼資料值與現有值不同，Compute Engine 會以新值更新區域中繼資料項目。
  - 如果指定的中繼資料值與現有值相同，區域中繼資料項目就不會變更。

範例：新增可用區中繼資料項目

舉例來說，假設有個名為 my-project 的專案，具有下列自訂中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
「us-central1-a」可用區中的可用區中繼資料："key-1":"value-1" 和 "key-2":"value-2"

如要在 us-central1-a 區域中新增 "key-4":"value-4" 做為新的自訂區域中繼資料配對，請執行下列指令：

gcloud compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

範例：更新現有自訂可用區中繼資料項目的值

請參考同一個範例專案 my-project，該專案現在具有下列自訂中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
us-central1-a 可用區中的可用區中繼資料："key-1":"value-1"、"key-2":"value-2" 和 "key-4":"value-4"

如要使用新值更新 us-central1-a 可用區中 key-1 和 key-4 的可用區中繼資料值，請執行下列指令。

gcloud compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

範例：覆寫金鑰的專案中繼資料值，並使用區域中繼資料值

請參考同一個範例專案 my-project，該專案現在具有下列自訂中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
us-central1-a 可用區中的可用區中繼資料："key-1":"new-value-1"、"key-2":"value-2" 和 "key-4":"new-value-4"

在本範例專案中，請考慮 key-3，其專案中繼資料值為 value-c。假設您要為 us-central1-a 可用區中的所有 VM，設定這個金鑰的可用區中繼資料值 value-3。執行作業時，Compute Engine 會針對 us-central1-a 區域中的所有 VM 覆寫專案中繼資料值，並使用區域中繼資料值。專案中其他可用區的 VM 會保留 key-3 的現行專案或可用區中繼資料值。

如要覆寫 key-3 的專案中繼資料值，並設定可用區中繼資料值，請執行下列指令：

gcloud compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

取得目前指紋，並查看該可用區中專案的任何現有鍵/值組合。

如要執行樂觀鎖定，您必須提供指紋。指紋是 Compute Engine 產生的隨機字元字串。每次要求新增、更新或移除區域中繼資料時，指紋都會變更。如果提供的指紋不符，Compute Engine 會拒絕您的要求。

如果未提供指紋，系統會檢查一致性，更新要求將無法成功。這樣一來，一次只能提出一項要求，避免發生衝突。此行為與 instances().setMetadata 相符，一律需要指紋。

如要取得可用區中繼資料的目前指紋，請向 instanceSettings().get 方法發出 GET 要求。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings
```
更改下列內容：
- PROJECT_ID：專案 ID
- ZONE：要設定區域中繼資料的區域。
以下是這項要求的輸出範例：
```
    {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }
```
如要新增或更新可用區中繼資料，請向 instanceSettings().patch 方法提出 PATCH 要求。請務必在要求中提供下列資訊：
- 更新遮罩。使用 update_mask 查詢參數。更新遮罩必須包含下列項目的中繼資料鍵：
  - 要新增的自訂可用區中繼資料
  - 要更新值的現有自訂可用區中繼資料
  您必須為每個鍵加上 metadata.items. 字串做為前置字串，例如 metadata.items.key1,metadata.items.key3。
  
  重要事項： 更新遮罩必須使用小寫。
- 在要求主體中提供下列資訊：
  - 要新增的自訂可用區中繼資料鍵和值
  - 要更新的現有自訂可用區中繼資料的中繼資料鍵和值
  - 目前的指紋值
注意： 如果您在更新遮罩中指定任何現有的自訂可用區中繼資料鍵，但未將其納入要求主體，Compute Engine 會移除這些可用區中繼資料項目。詳情請參閱「移除自訂可用區中繼資料」。
```
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}
```
更改下列內容：
- PROJECT_ID：專案 ID。
- ZONE：要設定可用區中繼資料的可用區。
- PREFIXED_METADATA_KEYS：下列項目的中繼資料鍵清單，每個鍵都以字串 metadata.items. 做為前置字元：
  - 要新增的自訂可用區中繼資料
  - 要更新值的現有自訂可用區中繼資料
  舉例來說，假設您在特定可用區中的目前可用區中繼資料鍵為 key-1 和 key-2。如要新增金鑰 (key-3)，並更新現有金鑰的可用區中繼資料 (key-1)，更新遮罩必須包含下列字串：
  
  metadata.items.key1,metadata.items.key3
- FINGER_PRINT：目前的指紋值。
- KEY1、KEY2...：要新增或更新值的自訂可用區中繼資料鍵。指定您在更新遮罩中指定的所有自訂可用區中繼資料鍵。
  
  注意： 如果您在更新遮罩中指定任何現有的自訂可用區中繼資料鍵，但未將其納入要求主體，Compute Engine 會移除這些可用區中繼資料項目。詳情請參閱「移除自訂區域中繼資料」。
- VALUE1、VALUE2...：要為現有和新的自訂中繼資料鍵設定的區域中繼資料值。視自訂中繼資料鍵和值而定，系統會執行下列其中一項操作：
  - 如果對應的自訂中繼資料鍵是具有專案中繼資料的現有鍵，則在指定區域中，Compute Engine 會以您指定的區域中繼資料值，覆寫該鍵的專案中繼資料值。專案中指定可用區內的所有 VM，都會繼承該鍵新指定的可用區中繼資料，其他可用區中的 VM 則會繼續保留現有的專案或可用區中繼資料值。如果您日後更新這個鍵的專案中繼資料值，專案中這個可用區的 VM 仍不會受到影響，並會繼續使用這個鍵的可用區中繼資料值。
  - 如果對應的自訂中繼資料鍵是新的中繼資料鍵，且未用於現有專案或區域中繼資料，則 Compute Engine 會建立自訂中繼資料鍵，並將這個值設為指定區域中的區域中繼資料。
  - 如果相應的自訂中繼資料鍵是現有的中繼資料鍵，且在指定可用區中具有可用區中繼資料值：
  - 如果指定的中繼資料值與現有值不同，Compute Engine 會以新值更新可用區中繼資料項目。
  - 如果指定的中繼資料值與現有值相同，區域中繼資料項目就不會變更。

範例：新增自訂可用區中繼資料項目

舉例來說，假設有個名為 my-project 的專案，具有下列自訂中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
「us-central1-a」可用區中的可用區中繼資料："key-1":"value-1" 和 "key-2":"value-2"

如要在 us-central1-a 區域中新增 "key-4":"value-4" 做為自訂可用區中繼資料配對，請發出下列 PATCH 要求：

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

範例：更新現有自訂可用區中繼資料項目的值

請參考同一個範例專案 my-project，該專案現在具有下列自訂中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
us-central1-a 可用區中的可用區中繼資料："key-1":"value-1"、"key-2":"value-2" 和 "key-4":"value-4"

如要使用新值更新 us-central1-a 區域中 key-1 和 key-4 的可用區中繼資料值，請發出下列 PATCH 要求：

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

範例：覆寫鍵的專案中繼資料值，並設定可用區中繼資料值

請參考同一個範例專案 my-project，該專案現在具有下列自訂中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
us-central1-a 可用區中的可用區中繼資料："key-1":"new-value-1"、"key-2":"value-2" 和 "key-4":"new-value-4"

在本範例專案中，請考慮 key-3，其專案中繼資料值為 value-c。假設您要為 us-central1-a 可用區中的所有 VM，設定這個金鑰的可用區中繼資料值 value-3。執行作業時，Compute Engine 會覆寫 us-central1-a 區域中所有 VM 的專案中繼資料值，並使用可用區中繼資料值。專案中其他可用區的 VM 會保留 key-3 的現行專案或可用區中繼資料值。

如要覆寫 key-3 的專案中繼資料值，並改用可用區中繼資料值 value-3，請提出下列 PATCH 要求：

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

設定自訂執行個體中繼資料

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST，為單一 VM 執行個體新增或更新自訂中繼資料。

您可以透過下列方式設定自訂執行個體中繼資料：

如果是新的 VM，您可以在建立 VM 時新增自訂中繼資料。
如果是現有 VM，您可以在 VM 執行時新增或更新自訂中繼資料。

在建立 VM 時新增自訂執行個體中繼資料

請按照這些操作說明，在建立特定 VM 執行個體時新增中繼資料。

控制台

前往 Google Cloud 控制台的「建立執行個體」頁面。

前往「建立執行個體」
指定 VM 詳細資料。
展開「Advanced options」(進階選項) 區段，然後執行下列操作：
1. 展開「管理」部分。
2. 如要為自訂中繼資料新增多個鍵/值組合，請在「中繼資料」部分點選「新增項目」。
按一下「Create」(建立)，即可建立 VM。

gcloud

如要設定自訂中繼資料，請使用 gcloud compute instances create 指令搭配 --metadata 旗標。

gcloud compute instances create VM_NAME \
--zone=ZONE \
--image-project=IMAGE_PROJECT \
IMAGE_FLAG \
--metadata=KEY=VALUE

更改下列內容：

VM_NAME：VM 名稱
ZONE：要建立 VM 的可用區
IMAGE_PROJECT：包含 VM 映像檔的專案
IMAGE_FLAG：指定下列其中一個值：
- 使用 --image IMAGE_NAME 旗標指定公開映像檔的特定版本。
  
  例如 --image debian-12-bookworm-v20241112。
- 使用 --image-family IMAGE_FAMILY_NAME 旗標指定映像檔系列。
  
  系統會使用映像檔系列中未淘汰的最新 OS 映像檔，建立 VM。舉例來說，如果您指定 --image-family debian-12，Compute Engine 會使用 Debian 12 映像檔系列中的最新版 OS 映像檔。
KEY：中繼資料鍵名稱
VALUE：這個鍵儲存的值

範例

舉例來說，如要在名為 example-instance 的 VM 上設定新金鑰 env，並將值設為 test，請執行下列指令：

 gcloud compute instances create example-instance \
   --zone=us-central1-a --image-project=debian-cloud \
   --image-family=debian-12 \
   --metadata=env=test

REST

使用 instances.insert 方法，並在要求中提供自訂中繼資料做為 metadata 屬性的一部分：

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

更改下列內容：

PROJECT_ID：專案 ID
ZONE：要在其中建立 VM 的可用區
MACHINE_TYPE：新 VM 的機型，可以是預先定義或自訂機型
VM_NAME：新 VM 的名稱
KEY：中繼資料鍵的名稱
VALUE：這個鍵儲存的值

在現有 VM 上新增或更新自訂執行個體中繼資料

請按照這些操作說明，更新現有特定 VM 執行個體的中繼資料。

控制台

前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面。
前往「VM instances」(VM 執行個體) 頁面
按一下您要更新中繼資料的執行個體。
按一下頁面頂端的 [編輯] 按鈕。
在「Custom metadata」(自訂中繼資料)下，按一下 [Add item] (新增項目) 或編輯現有中繼資料項目。
儲存變更。

gcloud

使用 gcloud CLI 更新 VM 中繼資料時，系統會新增中繼資料。請僅指定您要新增或變更的中繼資料鍵。如果您提供的鍵已經存在，該鍵的值就會更新為新值。

使用 instances add-metadata 指令：

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

更改下列內容：

VM_NAME：VM 名稱
KEY：中繼資料鍵名稱
VALUE：這個鍵儲存的值

範例

如要新增 foo=bar 項目，請使用：

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

如果您要將 foo=bar 項目變更為 foo=bat，請使用：

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

取得目前的指紋，並查看 VM 現有的鍵/值組合。如要這麼做，請呼叫 instances().get 方法。

指紋是由 Compute Engine 產生的隨機字串，用於執行樂觀鎖定。如要更新 VM，您必須提供相符的指紋值。每次提出要求後，指紋都會變更，如果提供的指紋不符，系統就會拒絕要求。這樣一來，一次只能進行一項更新，避免發生衝突。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
更改下列內容：
- PROJECT_ID：專案 ID
- ZONE：VM 所在的可用區
- VM_NAME：VM 名稱
輸出結果會與下列內容相似：
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}
```
向 instances().setMetadata 方法提出要求。請提供新中繼資料值和目前 fingerprint 值的清單。

如果 VM 含有您想保留的現有鍵/值組合，請務必將這些組合與新的鍵/值組合一併納入這項要求。

範例
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "zhma6O1w2l8=",
"items": [
  {
    "key": "foo",
    "value": "bar"
  },
  {
    "key": "baz",
    "value": "bat"
  }
]
}
```
更改下列內容：
- PROJECT_ID：專案 ID
- ZONE：VM 所在的可用區
- VM_NAME：VM 名稱

從 VM 移除自訂中繼資料

本節說明如何透過下列任一方式，移除 Compute Engine VM 的自訂中繼資料項目：

移除自訂專案中繼資料：移除為專案中所有 VM 設定的自訂中繼資料。
移除自訂可用區中繼資料，藉此移除專案中特定可用區內所有 VM 的自訂中繼資料。
移除自訂執行個體中繼資料，移除為特定 VM 設定的 VM 中繼資料。

移除自訂專案中繼資料

您可以使用 Google Cloud 控制台或 Google Cloud CLI 移除自訂專案中繼資料。

控制台

前往 Google Cloud 控制台的「Metadata」頁面。

前往「中繼資料」頁面
按一下頁面頂端的「編輯」。
找出要移除的中繼資料項目，然後按一下該項目旁邊的刪除按鈕。

針對要移除的每個中繼資料項目重複執行這個步驟。
如要完成移除自訂專案中繼資料項目，請按一下「Save」(儲存)。

gcloud

如要移除自訂專案中繼資料，請使用 gcloud compute project-info remove-metadata 指令。

如要移除特定鍵的自訂中繼資料項目，請使用 --keys 旗標指定這些鍵，並排除這些鍵的值。

gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...

如要移除 VM 的所有自訂中繼資料，請指定 --all 標記。

gcloud compute project-info remove-metadata \
    --all

更改下列內容：

KEY1、KEY2...：要移除的自訂執行個體中繼資料鍵。

移除自訂可用區中繼資料

您可以使用 Google Cloud CLI 或 REST 移除自訂可用區中繼資料。

gcloud

如要移除自訂區域中繼資料，請使用 gcloud compute project-zonal-metadata remove 指令，並使用 --keys 旗標指定要移除的所有中繼資料鍵。

gcloud compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

更改下列內容：

PROJECT_ID：專案 ID
ZONE：要移除區域中繼資料的區域。
KEY1、KEY2...：要移除的自訂區域中繼資料鍵。

執行指令後，如果任何指定鍵有可用的專案中繼資料值，指定可用區中的 VM 就會沿用這些專案中繼資料值。如果中繼資料項目只在可用區層級設定，且該鍵沒有對應的專案中繼資料值，則該可用區中的 VM 會失去該中繼資料資訊。

範例：

假設範例專案 my-project 具有下列自訂專案中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
us-central1-a 可用區中的可用區中繼資料："key-1":"new-value-1"、"key-2":"value-2"、"key-3":"value-3" 和 "key-4":"new-value-4"

如要移除 us-central1-a 區域中的所有可用區中繼資料，請執行下列指令。

gcloud compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

執行指令後，us-central1-a 可用區中的 VM 會擁有下列自訂專案中繼資料項目：

"key-1":"value-a"
"key-2":"value-b"
"key-3":"value-c"

REST

取得目前的指紋，並查看該可用區中專案的任何現有鍵/值組合。

如要執行樂觀鎖定，您必須提供指紋。指紋是 Compute Engine 產生的隨機字元字串。每次要求新增、更新或移除區域中繼資料時，指紋都會變更。如果提供的指紋不符，Compute Engine 會拒絕您的要求。

如果未提供指紋，系統會檢查一致性，且刪除要求不會成功。這樣一來，一次只能提出一項要求，避免發生衝突。這項行為與 instances().setMetadata 相同，一律需要指紋。

如要取得專案目前的指紋，請呼叫 instanceSettings().get 方法。
```
GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
```
更改下列內容：
- PROJECT_ID：專案 ID
- ZONE：要移除可用區中繼資料的可用區。
以下是這項要求的輸出範例：
```
    {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }
```
如要移除自訂可用區中繼資料，請向 instanceSettings().patch 方法提出 PATCH 要求，並從要求主體中排除要移除可用區中繼資料的中繼資料索引鍵。提出要求時，請務必提供下列資訊：
- 更新遮罩。使用 update_mask 查詢參數。更新遮罩必須包含所有現有的自訂中繼資料鍵，您要移除可用區中繼資料。您必須在每個鍵前面加上字串 metadata.items.，例如 metadata.items.key1,metadata.items.key3。
  
  重要事項： 更新遮罩必須使用小寫。
- 在要求主體中，僅提供目前的指紋值。排除您在更新遮罩中指定的所有自訂中繼資料鍵。如果您在更新遮罩和要求主體中都加入任何中繼資料鍵，Compute Engine 就不會移除這些鍵的區域中繼資料。
```
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}
```
更改下列內容：
- PROJECT_ID：專案 ID。
- ZONE：要移除區域中繼資料的區域。
- PREFIXED_METADATA_KEYS：要移除區域中繼資料的所有現有自訂中繼資料鍵清單，每個鍵都會加上 metadata.items. 字串前置字元。為確保刪除要求成功，請從要求主體中排除這些中繼資料鍵。如果您在更新遮罩和要求主體中都加入任何中繼資料鍵，Compute Engine 就不會移除這些鍵的區域中繼資料。
  
  舉例來說，假設您目前的區域中繼資料中繼資料鍵為 key-1、key-2、key-3 和 key-4，且您想移除 key-1 和 key-2 的區域中繼資料項目，則更新遮罩必須包含下列字串：
  
  metadata.items.key1,metadata.items.key2
- FINGER_PRINT：目前的指紋值。

提出要求後，如果任何指定鍵有可用的專案中繼資料值，指定可用區中的 VM 就會沿用這些專案中繼資料值。如果中繼資料金鑰只在可用區層級設定，且該金鑰沒有對應的專案中繼資料值，則該可用區中的 VM 會失去該中繼資料資訊。

範例：

假設範例專案 my-project 具有下列自訂專案中繼資料：

專案中繼資料："key-1":"value-a"、"key-2":"value-b" 和 "key-3":"value-c"
us-central1-a 地區中的可用區中繼資料："key-1":"new-value-1"、"key-2":"value-2"、"key-3":"value-3" 和 "key-4":"new-value-4"

如要移除 us-central1-a 可用區中 key-1 和 key-2 的可用區中繼資料，請提出下列 PATCH 要求。

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

這項要求通過後，us-central1-a 可用區中的 VM 就會擁有下列自訂中繼資料。VM 會沿用 key-1 和 key-2 的專案中繼資料值，但會保留 key-3 和 key-4 的可用區中繼資料。

專案中繼資料："key-1":"value-a" 和 "key-2":"value-b"
us-central1-a 可用區中的可用區中繼資料："key-3":"value-3" 和 "key-4":"new-value-4"

移除自訂執行個體中繼資料

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST 移除自訂執行個體中繼資料。

控制台

前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面。
前往「VM instances」(VM 執行個體) 頁面
在「Name」(名稱) 欄中，按一下要移除中繼資料的 VM 名稱。
按一下頁面頂端的「編輯」。
在「Metadata」(中繼資料) 專區中，針對要移除的每個中繼資料項目，按一下「Delete item」(刪除項目)。
如要確認變更並移除自訂執行個體中繼資料，請按一下「儲存」。

gcloud

如要移除自訂執行個體中繼資料，請使用 gcloud compute instances remove-metadata 指令。

如要移除特定鍵的自訂中繼資料項目，請使用 --keys 旗標指定這些鍵，並排除這些鍵的值。

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...

如要移除 VM 的所有自訂中繼資料，請指定 --all 標記。

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

更改下列內容：

PROJECT_ID：您的專案 ID。
ZONE：VM 的可用區。
VM_NAME：VM 名稱
KEY1、KEY2...：要移除的自訂執行個體中繼資料鍵。

REST

取得目前的指紋，並查看 VM 的所有現有鍵值組。如要這麼做，請呼叫 instances().get 方法。

指紋是 Compute Engine 產生的隨機字串，用於執行樂觀鎖定。如要更新 VM，您必須提供相符的指紋值。每次提出要求後，指紋都會變更，如果提供的指紋不符，系統就會拒絕要求。這樣一來，一次只能進行一項更新，避免發生衝突。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
更改下列內容：
- PROJECT_ID：您的專案 ID。
- ZONE：VM 的可用區。
- VM_NAME：VM 名稱
輸出結果會與下列內容相似：
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}
```
向 instances().setMetadata 方法提出要求。您必須在要求中加入目前的中繼資料指紋值，要求才會成功。
- 如要從 VM 移除所有自訂中繼資料鍵/值組合，請在 items 屬性中排除要移除中繼資料值的鍵。
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}
```
- 如要移除 VM 上的所有自訂執行個體中繼資料，請一併排除 items 屬性。
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": FINGER_PRINT
}
```
更改下列內容：
- PROJECT_ID：您的專案 ID。
- ZONE：VM 的可用區。
- VM_NAME：VM 名稱
- FINGER_PRINT：目前的指紋值。
- KEY1、KEY2...：要移除的自訂執行個體中繼資料鍵。
- VALUE1、VALUE2...：要移除的自訂執行個體中繼資料鍵值。

後續步驟

瞭解如何查看及查詢中繼資料。
進一步瞭解如何在 Metadata 伺服器中執行開機指令碼或關機指令碼。

設定及移除自訂中繼資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

控制台

gcloud

REST

必要的角色

所需權限

限制

大小限制

字串大小寫限制

可用區中繼資料限制

布林值

設定 VM 的自訂中繼資料

設定自訂專案中繼資料

控制台

gcloud

REST

設定自訂可用區中繼資料

設定自訂可用區中繼資料前的注意事項

程序

gcloud

範例：新增可用區中繼資料項目

範例：更新現有自訂可用區中繼資料項目的值

範例：覆寫金鑰的專案中繼資料值，並使用區域中繼資料值

REST

範例：新增自訂可用區中繼資料項目

範例：更新現有自訂可用區中繼資料項目的值

範例：覆寫鍵的專案中繼資料值，並設定可用區中繼資料值

設定自訂執行個體中繼資料

在建立 VM 時新增自訂執行個體中繼資料

控制台

gcloud

REST

在現有 VM 上新增或更新自訂執行個體中繼資料

控制台

gcloud

REST

從 VM 移除自訂中繼資料

移除自訂專案中繼資料

控制台

gcloud

移除自訂可用區中繼資料

gcloud

範例：

REST

範例：

移除自訂執行個體中繼資料

控制台

gcloud

REST

後續步驟

設定及移除自訂中繼資料