设置和移除自定义元数据

Linux Windows

每个元数据条目以键值对的形式存储在元数据服务器上。元数据键区分大小写。您的键可以是预定义键，也可以是自定义元数据键。

通过自定义元数据，您可以在单个虚拟机或项目中创建和使用自己的元数据键值对。您可以添加新的自定义元数据键，更新现有键的值，以及移除不需要的任何自定义元数据条目。设置自定义元数据对于将任意值传递给项目中的虚拟机非常有用。它对创建启动和关停脚本也有用。

本文档介绍了如何执行以下操作：

在虚拟机上添加或更新自定义元数据
从虚拟机中移除自定义元数据

准备工作

查看有关如何定义 Compute Engine 的虚拟机元数据、对其进行分类和安排的基础知识。如需了解详情，请参阅虚拟机元数据简介。

设置身份验证（如果尚未设置）。身份验证是通过其进行身份验证以访问 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. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

所需的角色

如需获得在虚拟机上设置或移除自定义元数据所需的权限，请让您的管理员向您授予以下 IAM 角色：

针对虚拟机或项目的 Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
如果您的虚拟机使用服务账号：针对服务账号或项目的 Service Account User (roles/iam.serviceAccountUser)

如需详细了解如何授予角色，请参阅管理访问权限。

这些预定义角色包含在虚拟机上设置或移除自定义元数据所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需在虚拟机上设置或移除自定义元数据，您需要具备以下权限：

如果您的虚拟机使用服务账号：针对服务账号或项目的 iam.serviceAccounts.actAs
如需添加、更新或移除自定义项目元数据：
- 针对项目的 compute.projects.get 权限
- 针对项目的 compute.projects.setCommonInstanceMetadata 权限
如需添加、更新或移除自定义可用区元数据：
- 对项目中所需可用区的实例设置的 compute.instanceSettings.get 权限
- 对项目中所需可用区的实例设置的 compute.instanceSettings.update 权限
如需添加、更新或移除自定义实例元数据：
- 针对虚拟机的 compute.instances.get 权限
- 针对虚拟机的 compute.instances.setMetadata 权限

您也可以使用自定义角色或其他预定义角色来获取这些权限。

限制

Compute Engine 会对所有元数据条目实施总大小限制（即 512 KB）。最大大小限制还通过以下方式应用于每个 key 和 value：

每个元数据 key 的大小上限为 128 字节。
每个元数据 key 都区分大小写。

对于可用区元数据，Compute Engine 不允许创建具有相同字符串的两个单独元数据键，即使它们在不同情况下编写也是如此。例如，如果可用区级元数据已有名为 project-zonal-metadata-key 的自定义元数据键，则对于该可用区中的可用区级元数据，您无法创建新的元数据键，例如 Project-Zonal-Metadata-Key、PROJECT-ZONAL-METADATA-KEY 或同一字符串的任何其他变体。
每个元数据 value 的大小上限为 256 KB。
除了布尔值之外，每个元数据 value 都区分大小写。

例如，SSH 键会以自定义元数据的形式存储在 ssh-keys 键下。如果此键的元数据内容或 value 超过 256 KB 的限制，您将无法添加更多 SSH 键。如果您受到此限制约束，请考虑移除未使用的键以为新键释放元数据空间。

此外，如果您直接提供启动或关停脚本内容，则这些启动和关停脚本内容也可能会存储为自定义元数据，并计入这些大小限制。为了避免出现这种情况，请将启动或关停脚本存储为文件，并将其托管在 Cloud Storage 等外部位置，然后在创建实例时提供启动脚本网址。这样，这些文件就会下载到虚拟机上，而不是存储在元数据服务器中。

布尔值

对于接受布尔值（TRUE 或 FALSE）的字段，还可以使用以下值：

状态	替代值
`TRUE`	`Y`、`Yes`、`1`
`FALSE`	`N`、`No`、`0`

布尔值不区分大小写。例如，您可以使用 False、false 或 FALSE 停用某项功能。

在虚拟机上设置自定义元数据

本部分介绍如何通过以下任一方式为 Compute Engine 虚拟机添加新的自定义元数据或更新现有自定义元数据值：

设置自定义项目元数据，为您项目中的所有虚拟机添加或更新自定义项目元数据。
设置自定义可用区级元数据，为项目中的虚拟机添加或更新可用区级自定义元数据。
设置自定义实例元数据，为特定虚拟机添加或更新自定义实例元数据。

设置自定义项目元数据

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST 为项目中的所有实例添加或更新自定义元数据。

使用以下说明将元数据设置应用于项目中的所有虚拟机。例如，如果您定义了项目元数据对 baz=bat，则该元数据对将自动应用于项目中的所有虚拟机。

控制台

在 Google Cloud 控制台中，转到元数据页面。
转到“自定义元数据”页面
点击页面顶部的修改。
如需添加新的自定义项目元数据条目，请执行以下操作：
1. 导航到页面底部，然后点击 添加项。
2. 在键字段中，输入自定义元数据键的名称。
3. 在值字段中，输入自定义项目元数据值。
4. 可选。如需添加更多自定义项目元数据条目，请对要添加的每个元数据条目重复上述步骤。
5. 如需完成自定义项目元数据条目的添加，请点击保存。
如需修改现有的自定义项目元数据条目，请执行以下操作：
1. 转到要修改的元数据条目。
2. 如需更新特定自定义元数据键的名称，请在该条目的键字段中输入新名称。
3. 如需更新自定义项目元数据条目的值，请在该条目的值字段中输入新值。
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。

设置自定义可用区级元数据

设置自定义可用区元数据时，您可以为项目内特定可用区中的虚拟机添加或更新可用区元数据条目。您可以通过设置自定义可用区元数据来执行以下操作：

为项目中的特定可用区创建新的自定义元数据键，并为该项目的该可用区中的所有虚拟机设置元数据。
更新项目中特定可用区中所有虚拟机的现有自定义可用区元数据条目的值。
对于具有项目元数据值的现有自定义元数据键，请替换特定可用区中的这些项目元数据值，并改为设置可用区元数据。在特定可用区中为这些键设置可用区元数据后，该项目中该可用区的所有虚拟机都将使用这些键的可用区元数据值。

设置自定义可用区元数据之前的注意事项

项目和可用区元数据条目存储在同一 project/ 目录中。如果您在项目级和可用区级的虚拟机上为同一自定义元数据键设置了不同的值，则这些键的可用区元数据值优先于相应可用区中的项目元数据。

如果您为已具有项目元数据值的元数据键添加可用区元数据值，则 Compute Engine 将替换此指定可用区中虚拟机的项目元数据值，并使用可用区值更新 /project 目录。
如果您为已具有可用区元数据值的元数据键添加新的项目范围元数据值，则系统不会进行任何更改。Compute Engine 会将可用区元数据值保留在特定可用区的 /project 目录中。
如果您没有为特定可用区中的自定义元数据键指定可用区元数据值，但键具有项目元数据值，则您的虚拟机将继续在这些可用区中具有项目元数据值。

过程

您可以使用 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 会在指定的可用区中用您指定的可用区元数据值替换键的项目元数据值。项目中指定可用区中的所有虚拟机都会继承该键的这个新指定的可用区级元数据，其他可用区中的虚拟机将继续保留其主要的项目或可用区元数据值。如果您对此键的项目元数据值进行任何未来更新，则项目中此可用区的虚拟机不会受影响，并继续为此键使用可用区元数据值。
- 如果相应的自定义元数据键是未用于现有项目或可用区元数据的新元数据键，则 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"

如需将 "key-4":"value-4" 添加为 us-central1-a 可用区中的新自定义可用区元数据对，请运行以下命令：

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 可用区中所有虚拟机的此键设置可用区级元数据值 value-3。执行操作时，对于 us-central1-a 可用区中的所有虚拟机，Compute Engine 会替换项目元数据值并使用可用区元数据值。项目所有其他可用区中的虚拟机会保留其 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 会在指定的可用区中用您指定的可用区元数据值替换键的项目元数据值。项目中指定可用区中的所有虚拟机都会继承该键的这个新指定的可用区级元数据，其他可用区中的虚拟机将继续保留其主要的项目或可用区元数据值。如果您对此键的项目元数据值进行任何未来更新，则项目中此可用区的虚拟机不会受影响，并继续为此键使用可用区元数据值。
  - 如果相应的自定义元数据键是尚未用于现有项目或可用区元数据的新元数据键，则 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"

如需将 "key-4":"value-4" 添加为 us-central1-a 可用区中的新自定义可用区元数据对，请发出以下 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 添加或更新单个虚拟机实例的自定义元数据。

您可以通过以下某种方式设置自定义实例元数据：

对于新虚拟机，您可以在创建虚拟机时添加自定义元数据。
对于现有虚拟机，您可以在虚拟机运行时添加或更新自定义元数据。

在创建虚拟机期间添加自定义实例元数据

使用以下说明在创建虚拟机时添加特定虚拟机实例上的元数据。

控制台

在 Google Cloud 控制台中，转到创建实例页面。

转到“创建实例”
指定虚拟机详情。
展开高级选项部分，然后执行以下操作：
1. 展开管理部分。
2. 如需为自定义元数据添加多个键值对，请点击元数据部分中的添加一项。
如需创建虚拟机，请点击创建。

gcloud

如需设置自定义元数据，请使用带有 --metadata 标志的 gcloud compute instances create 命令。

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

请替换以下内容：

VM_NAME：您的虚拟机的名称
KEY：元数据键的名称
VALUE：为此键存储的值

示例

例如，如需在名为 example-instance 的虚拟机上设置值为 bar 的新键 foo，请运行以下命令：

gcloud compute instances create example-instance \
    --metadata=foo=bar

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：要在其中创建虚拟机的可用区
MACHINE_TYPE：新虚拟机的预定义或自定义机器类型
VM_NAME：新虚拟机的名称
KEY：元数据键的名称
VALUE：为此键存储的值

在现有虚拟机上添加或更新自定义实例元数据

使用以下说明可更新已存在的特定虚拟机实例上的元数据。

控制台

在 Google Cloud 控制台中，前往虚拟机实例页面。
转到“虚拟机实例”页面
点击您想要更新其元数据的实例。
点击页面顶部的修改按钮。
在自定义元数据下，点击添加一项或修改现有的元数据条目。
保存更改。

gcloud

使用 gcloud CLI 更新虚拟机元数据是一项附加性操作。请仅指定您要添加或更改的元数据键。如果您提供的键已经存在，则系统将使用新值来更新该键对应的值。

使用 instances add-metadata 命令：

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

请替换以下内容：

VM_NAME：您的虚拟机的名称
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

获取当前指纹并查看虚拟机的任何现有键值对。为此，请调用 instances().get 方法。

指纹是由 Compute Engine 生成的随机字符串，可用于执行乐观锁定。如需更新虚拟机，您需要提供匹配的指纹值。每次请求后指纹都会更改，因此如果您提供的指纹不匹配，请求将被拒绝。这样，一次就只能进行一项更新，以免发生冲突。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
替换以下内容：
- PROJECT_ID：您的项目 ID
- ZONE：虚拟机所在的可用区
- VM_NAME：您的虚拟机的名称
输出类似于以下内容：
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}
```
向 instances().setMetadata 方法发出请求。请提供新元数据值和当前 fingerprint 值的列表。

如果您想要保留虚拟机的现有键值对，则必须将这些现有键值对和新键值对都加入此请求中。

示例
```
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_NAME：您的虚拟机的名称

从虚拟机中移除自定义元数据

本部分介绍如何通过以下任一方式移除 Compute Engine 虚拟机的自定义元数据条目：

移除自定义项目元数据，以移除为项目中的所有虚拟机设置的自定义元数据。
移除自定义可用区元数据，以移除为项目中特定可用区中的所有虚拟机设置的自定义元数据。
移除自定义实例元数据，以移除为特定虚拟机设置的虚拟机元数据。

移除自定义项目元数据

您可以使用 Google Cloud 控制台或 Google Cloud CLI 移除自定义项目元数据。

控制台

在 Google Cloud 控制台中，转到元数据页面。

转到“元数据”页面
点击页面顶部的修改。
找到要移除的元数据条目，然后点击该条目旁边的删除按钮。

对要移除的每个元数据条目重复此步骤。
如需完成自定义项目元数据条目的移除，请点击保存。

gcloud

如需移除自定义项目元数据，请使用 gcloud compute project-info remove-metadata 命令。

如果要移除特定键的自定义元数据条目，请使用 --keys 标志指定这些键，并排除这些键的值。

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

如果您要移除虚拟机的所有自定义元数据，请指定 --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...：要移除的自定义可用区元数据键。

运行该命令后，如果任何指定的键具有项目元数据值，则指定可用区中的虚拟机将继承这些项目元数据值。如果元数据条目仅在可用区级设置，并且该键没有相应的项目元数据值，则该可用区中的虚拟机会丢失该元数据信息。

示例：

假设有一个示例项目 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 可用区中的虚拟机具有以下自定义项目元数据条目：

"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：当前的指纹值。

发出请求后，如果任何指定的键具有项目元数据值，则指定可用区中的虚拟机将继承这些项目元数据值。如果元数据键仅在可用区级设置，并且该键没有相应的项目元数据值，则该可用区中的虚拟机会丢失该元数据信息。

示例：

假设有一个示例项目 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 可用区中的虚拟机将具有以下自定义元数据。虚拟机会继承 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 控制台中，前往虚拟机实例页面。
进入“虚拟机实例”页面
在名称列中，点击要移除其元数据的虚拟机的名称。
点击页面顶部的修改。
在元数据部分，针对要移除的每个元数据条目点击 删除项。
如需确认您的更改并移除自定义实例元数据，请点击保存。

gcloud

如需移除自定义实例元数据，请使用 gcloud compute instances remove-metadata 命令。

如果要移除特定键的自定义元数据条目，请使用 --keys 标志指定这些键，并排除这些键的值。

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

如果您要移除虚拟机的所有自定义元数据，请指定 --all 标志。

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

替换以下内容：

PROJECT_ID：您的项目 ID。
ZONE：您的虚拟机所在的可用区。
VM_NAME：您的虚拟机的名称
KEY1、KEY2...：要移除的自定义实例元数据键。

REST

获取当前指纹并查看虚拟机的任何现有键值对。为此，请调用 instances().get 方法。

指纹是由 Compute Engine 生成的随机字符串，可用于执行乐观锁定。如需更新虚拟机，您需要提供匹配的指纹值。每次请求后指纹都会更改，因此如果您提供的指纹不匹配，请求将被拒绝。这样，一次就只能进行一项更新，以免发生冲突。
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
替换以下内容：
- PROJECT_ID：您的项目 ID。
- ZONE：您的虚拟机所在的可用区。
- VM_NAME：您的虚拟机的名称
输出类似于以下内容：
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}
```
向 instances().setMetadata 方法发出请求。为了确保请求成功，您必须添加当前的元数据指纹值。
- 如需从虚拟机中移除所有自定义元数据键值对，请在 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"
  }
  ...
]
}
```
- 如需移除虚拟机上的所有自定义实例元数据，请完全排除 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_NAME：您的虚拟机的名称
- FINGER_PRINT：当前的指纹值。
- KEY1、KEY2...：要移除的自定义实例元数据键。
- VALUE1、VALUE2...：要移除的自定义实例元数据键的值。

后续步骤

详细了解虚拟机元数据。
了解如何查看和查询元数据。
详细了解如何在元数据服务器中运行启动脚本或关停脚本。

设置和移除自定义元数据

准备工作

Console

gcloud

REST

所需的角色

所需权限

限制

布尔值

在虚拟机上设置自定义元数据

设置自定义项目元数据

控制台

gcloud

REST

设置自定义可用区级元数据

设置自定义可用区元数据之前的注意事项

过程

gcloud

示例：添加新的自定义可用区级元数据条目

示例：更新现有自定义可用区元数据条目的值

示例：替换键的项目元数据值，并使用可用区元数据值

REST

示例：添加新的自定义可用区级元数据条目

示例：更新现有自定义可用区元数据条目的值

示例：替换键的项目元数据值，并设置可用区元数据值

设置自定义实例元数据

在创建虚拟机期间添加自定义实例元数据

控制台

gcloud

REST

在现有虚拟机上添加或更新自定义实例元数据

控制台

gcloud

REST

从虚拟机中移除自定义元数据

移除自定义项目元数据

控制台

gcloud

移除自定义可用区级元数据

gcloud

示例：

REST

示例：

移除自定义实例元数据

控制台

gcloud

REST

后续步骤