本頁面由 Cloud Translation API 翻譯而成。

設定及移除自訂中繼資料

Linux Windows

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

自訂中繼資料可讓您在個別 VM 或專案中，建立及使用自己的中繼資料鍵值組合。您可以新增自訂中繼資料鍵、更新現有鍵的值，以及移除不需要的自訂中繼資料項目。設定自訂中繼資料很適合用來將任意值傳入專案中的 VM。這也適合用來建立開機和關機指令碼。

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

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

事前準備

瞭解如何定義、分類及排列 Compute Engine 的 VM 中繼資料。詳情請參閱「關於 VM 中繼資料」。

如果尚未設定驗證，請先完成設定。「驗證」是指驗證身分的程序，確認您有權存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列任一選項，向 Compute Engine 進行驗證：

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. 安裝 Google Cloud CLI。安裝完成後，執行下列指令初始化 Google Cloud CLI：
  gcloud init
  如果您使用外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
  
  注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。
2. Set a default region and zone.
REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

必要的角色

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

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

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

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

所需權限

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

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

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

限制

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

大小限制

Compute Engine 會對所有中繼資料項目強制執行 512 KB 的合併總計限制。每個 key 和 value 也會套用大小上限，如下所示：

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

舉例來說，安全殼層 (SSH) 金鑰組會在 ssh-keys 金鑰下儲存為自訂中繼資料。如果這個金鑰的中繼資料內容或 value 超出 256 KB 的限制，您將無法新增更多安全殼層 (SSH) 金鑰組。如果遇到這個限制，請考慮移除不使用的金鑰，以便為新金鑰釋出中繼資料空間。

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

字串大小寫限制

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

可用區中繼資料限制

您只能使用 gcloud CLI 或 REST 設定及移除區域中繼資料。
您無法建立兩個字串相同的獨立中繼資料鍵，即使鍵的大小寫不同也一樣。舉例來說，如果特定區域的區域中繼資料已有名為 zonal-metadata-key 的自訂中繼資料鍵，您就無法建立與該字串類似的新區域中繼資料鍵，例如 Zonal-Metadata-Key 或 ZONAL-METADATA-KEY。
您無法為安全殼層 (SSH) 金鑰設定區域中繼資料值，因為這些金鑰會儲存在 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」頁面。
前往「Custom metadata」(自訂中繼資料) 頁面
按一下頁面頂端的「編輯」。
如要新增自訂專案中繼資料項目，請按照下列步驟操作：
1. 前往頁面底部，然後按一下「新增項目」。
2. 在「Key」欄位中，輸入自訂中繼資料鍵的名稱。
3. 在「Value」(值) 欄位中，輸入自訂專案中繼資料值。
4. (選用步驟) 如要新增更多自訂專案中繼資料項目，請針對要新增的每個中繼資料項目重複上述步驟。
5. 如要完成新增自訂專案中繼資料項目，請按一下「儲存」。
如要編輯現有的自訂專案中繼資料項目，請按照下列步驟操作：
1. 前往要編輯的中繼資料項目。
2. 如要更新特定自訂中繼資料鍵的名稱，請在該項目的「Key」欄位中輸入新名稱。
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-cerntral1-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-cerntral1-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-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 控制台的「Create an instance」(建立執行個體) 頁面。

前往「建立執行個體」
指定 VM 詳細資料。
展開「Advanced options」(進階選項) 區段，然後執行下列操作：
1. 展開「管理」部分。
2. 如要為自訂中繼資料新增多個鍵值組合，請在「中繼資料」區段點選「新增項目」。
如要建立 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」頁面。

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

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

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...：要移除的自訂執行個體中繼資料鍵值。

後續步驟

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

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

事前準備

Console

gcloud

REST

必要的角色

所需權限

限制

大小限制

字串大小寫限制

可用區中繼資料限制

布林值

在 VM 上設定自訂中繼資料

設定自訂專案中繼資料

主控台

gcloud

REST

設定自訂可用區中繼資料

設定自訂可用區中繼資料前須知

程序

gcloud

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

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

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

REST

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

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

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

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

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

主控台

gcloud

REST

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

主控台

gcloud

REST

從 VM 移除自訂中繼資料

移除自訂專案中繼資料

主控台

gcloud

移除自訂可用區中繼資料

gcloud

範例：

REST

範例：

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

主控台

gcloud

REST

後續步驟

設定及移除自訂中繼資料