Cada máquina virtual (VM) armazena os metadados em diretórios em um servidor de metadados. O acesso da VM à API do servidor de metadados é fornecido automaticamente, sem qualquer autorização extra. Use os métodos explicados nas seguintes seções deste documento para visualizar e consultar os valores de metadados da VM:
- Consulte metadados de maneira programática dentro de uma VM
- Ver metadados personalizados das suas VMs
Antes de começar
- Para VMs do Windows Server, use o
PowerShell 3.0 ou posterior.
Recomendamos que você use
ctrl+v
para colar os blocos de código copiados. - Revise os conceitos básicos de como os metadados de VM para o Compute Engine são definidos, categorizados e organizados. Para mais informações, consulte Sobre metadados da VM.
-
Configure a autenticação, caso ainda não tenha feito isso.
A autenticação é
o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud.
Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no
Compute Engine da seguinte maneira.
Selecione a guia para como planeja usar as amostras nesta página:
Console
Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud, não é necessário configurar a autenticação.
gcloud
-
Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:
gcloud init
- Defina uma região e uma zona padrão.
Python
Para usar as amostras de Python nesta página de um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure o Application Default Credentials com as credenciais de usuário.
- Instale a CLI do Google Cloud.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
-
Crie as credenciais de autenticação para sua Conta do Google:
gcloud auth application-default login
Veja mais informações em: Configurar a autenticação para um ambiente de desenvolvimento local.
REST
Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.
Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:
gcloud init
-
Funções exigidas
Os papéis e as permissões a seguir são necessários para ver metadados personalizados de fora da VM usando o console do Google Cloud, a CLI do Google Cloud ou REST. Se você estiver consultando os metadados de maneira programática de dentro da VM, precisará apenas dos papéis e das permissões para se conectar a ela.
Para ter as permissões necessárias para ver metadados personalizados de fora da VM, peça ao seu administrador para conceder a você os seguintes papéis do IAM:
-
Administrador da instância do Compute (v1) (
roles/compute.instanceAdmin.v1
) na VM ou no projeto -
Se as VMs usam contas de serviço:
Usuário da conta de serviço (
roles/iam.serviceAccountUser
) na conta de serviço ou no projeto
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Esses papéis predefinidos contêm as permissões necessárias para ver metadados personalizados de fora da VM. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As permissões a seguir são necessárias para ver metadados personalizados de fora da VM:
- Para ver metadados personalizados em todo o projeto:
compute.projects.get
- Para ver metadados personalizados zonais do projeto:
compute.instanceSettings.get
-
Para ver metadados personalizados de uma instância de VM:
compute.instances.get
-
Se as VMs usarem contas de serviço:
iam.serviceAccounts.actAs
Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.
Consultar metadados programaticamente
Em uma VM, é possível consultar programaticamente valores de metadados padrão ou personalizados usando ferramentas como curl
no Linux ou Invoke-RestMethod
no Windows.
Partes de uma solicitação de metadados
A tabela a seguir resume as principais partes de uma solicitação de consulta de metadados.
Componentes | Descrição |
---|---|
URL raiz | Todos os valores de metadados são definidos como subcaminhos abaixo do seguinte URL raiz:
|
Cabeçalho da solicitação |
Esse cabeçalho indica que a solicitação foi enviada com a intenção de recuperar valores de metadados, em vez de recuperar involuntariamente de uma fonte insegura e permite que o servidor de metadados retorne os dados solicitados. Se você não fornecer esse cabeçalho, o servidor de metadados negará sua solicitação. Metadata-Flavor: Google |
Consultar uma única entrada de metadados
Use os comandos a seguir para consultar uma única entrada de metadados.
Linux
- Conecte-se à VM do Linux.
Na VM do Linux, use a ferramenta
curl
para fazer uma consulta.Para consultar uma entrada de metadados da instância de VM, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
Para consultar uma entrada de metadados do projeto, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
Substitua
METADATA_KEY
pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.Por exemplo, para consultar a imagem de inicialização da VM, execute a seguinte consulta:
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/image" -H "Metadata-Flavor: Google"
O resultado será assim:
projects/rhel-cloud/global/images/rhel-8-v20210122
Windows
- Conecte-se à VM do Windows:
Na VM do Windows, use o comando
Invoke-RestMethod
para fazer uma consulta.Para consultar uma entrada de metadados da instância de VM, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY") $value
Para consultar uma entrada de metadados do projeto, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY") $value
Substitua
METADATA_KEY
pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.Por exemplo, para consultar a imagem de inicialização da VM, execute a seguinte consulta:
PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/image") $value
O resultado será assim:
projects/windows-cloud/global/images/windows-server-2019-dc-v20210112
Consultar as listagens do diretório de metadados
Use os comandos a seguir para consultar as listagens do diretório de metadados. As listagens de diretórios são entradas de metadados que contêm outras chaves de metadados. Todas as entradas de metadados com uma barra no final do nome são listagens de diretórios.
Linux
Conecte-se à VM do Linux.
Na VM do Linux, execute os seguintes comandos:
Para consultar um diretório de metadados da instância de VM, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
Para consultar um diretório de metadados do projeto, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
Substitua
METADATA_DIRECTORY_NAME
pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listas.Por exemplo, considere a entrada
disks/
, que é um diretório de discos anexado à VM. Para consultar a entrada dedisks/
, siga estas etapas:Execute o comando
curl
ferramenta no diretório de discos.user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
O resultado será assim:
0/ 1/ 2/
Se você quiser mais informações sobre o diretório
0/
do disco, consulte o URL específico desse diretório:user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"
O resultado será assim:
device-name index mode type
Em seguida, para consultar o tipo de disco (
type
) para discos0/
, execute:user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type" -H "Metadata-Flavor: Google"
O resultado será assim:
PERSISTENT
Windows
A entrada disks/
é um diretório de discos anexado à VM.
Para consultar a entrada de discos, siga estas etapas:
Conecte-se à VM do Windows:
Na VM do Windows, execute os seguintes comandos:
Para consultar um diretório de metadados da instância de VM, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/") $value
Para consultar um diretório de metadados do projeto, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/") $value
Substitua
METADATA_DIRECTORY_NAME
pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listas.Por exemplo, considere a entrada
disks/
, que é um diretório de discos anexado à VM. Para consultar a entrada dedisks/
, siga estas etapas:Execute o
Invoke-RestMethod
comando no diretório de discos.PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/") $value
O resultado será assim:
0/ 1/ 2/
Se você quiser mais informações sobre o diretório
0/
do disco, consulte o URL específico desse diretório:PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/") $value
O resultado será assim:
device-name index mode type
Em seguida, para consultar o tipo de disco (
type
) para discos0/
, execute:PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type") $value
O resultado será assim:
PERSISTENT
Consultar as listagens de diretórios de maneira recursiva
Se você quiser retornar todo o conteúdo em um diretório, use o parâmetro de consulta recursive=true
com a sua solicitação:
Linux
Conecte-se à VM do Linux.
Na VM do Linux, use a ferramenta
curl
para fazer uma consulta.Para consultar recursivamente as listagens de um diretório de metadados da instância de VM, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
Para consultar recursivamente as listagens de um diretório de metadados do projeto, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
Substitua
METADATA_DIRECTORY_NAME
pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listagens de maneira recursiva.Por exemplo, o comando a seguir consulta de maneira recursiva as listagens de metadados da instância para o diretório
disks/
.user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"
O resultado será assim:
[{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"}, {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"}, {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
Por padrão, o conteúdo recursivo é retornado no formato JSON. Se desejar retornar esses conteúdos no formato de texto, anexe o parâmetro de consulta
alt=text
:user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"
O resultado será assim:
0/device-name boot 0/index 0 0/mode READ_WRITE 0/type PERSISTENT 1/device-name persistent-disk-1 1/index 1 1/mode READ_WRITE 1/type PERSISTENT 2/device-name persistent-disk-1 2/index 2 2/mode READ_ONLY 2/type PERSISTENT
Windows
Conecte-se à VM do Windows:
Na VM do Windows, use o comando
Invoke-RestMethod
para fazer uma consulta.Para consultar recursivamente as listagens de um diretório de metadados da instância de VM, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true") $value
Para consultar recursivamente as listagens de um diretório de metadados do projeto, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true") $value
Substitua
METADATA_DIRECTORY_NAME
pelo nome da instância ou do diretório de metadados do projeto em que você quer consultar as listagens de maneira recursiva.Por exemplo, o comando a seguir consulta de maneira recursiva as listagens de metadados da instância para o diretório
disks/
.PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true") $value
O resultado será assim:
[{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"}, {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"}, {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
Por padrão, o conteúdo recursivo é retornado no formato JSON. Se desejar retornar esses conteúdos no formato de texto, anexe o parâmetro de consulta
alt=text
:PS C:\> $value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text") $value
O resultado será assim:
0/device-name boot 0/index 0 0/mode READ_WRITE 0/type PERSISTENT 1/device-name persistent-disk-1 1/index 1 1/mode READ_WRITE 1/type PERSISTENT 2/device-name persistent-disk-1 2/index 2 2/mode READ_ONLY 2/type PERSISTENT
Formatar a saída de consulta
Por padrão, cada endpoint tem um formato de resposta predefinido. Em alguns pontos de extremidade, os dados podem ser retornados no formato JSON por padrão. Em outros, eles são retornados como uma string. É possível substituir a especificação de formato de dados padrão
usando os parâmetros de consulta alt=json
ou alt=text
, que retornam dados no formato de
string JSON ou como uma representação de texto simples, respectivamente.
Linux
- Conecte-se à VM do Linux.
Na VM do Linux, use a ferramenta
curl
para fazer uma consulta.Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados da instância de VM, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados do projeto, execute o seguinte comando:
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
Substitua:
METADATA_KEY
: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.DATA_FORMAT
: o formato em que você quer os dados de resposta da consulta. Por exemplo,text
oujson
.
Exemplo
Por exemplo, a tecla tags
retorna automaticamente os dados no formato JSON. No entanto, é possível retornar dados em formato de texto
especificando o parâmetro de consulta alt=text
.
Consulta padrão
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
O resultado será assim:
["http-server", "db-client", "app-server", "mysql-server"]
Consulta com formatação
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"
O resultado será assim:
http-server db-client app-server mysql-server
Windows
- Conecte-se à VM do Windows:
Na VM do Windows, use o comando
Invoke-RestMethod
para fazer uma consulta.Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados da instância de VM, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT") $value
Para alterar o formato dos dados da resposta da consulta para uma entrada de metadados do projeto, execute o seguinte comando:
$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT") $value
Substitua:
METADATA_KEY
: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.DATA_FORMAT
: o formato em que você quer os dados de resposta da consulta. Por exemplo,text
oujson
.
Exemplo
Por exemplo, a tecla tags
retorna automaticamente os dados no formato JSON. No entanto, é possível retornar dados em formato de texto
especificando o parâmetro de consulta alt=text
.
Consulta padrão
PS C:>
$value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags")
$value
O resultado será assim:
["http-server", "db-client", "app-server", "mysql-server"]
Consulta com formatação
PS C:>
$value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
$value
O resultado será assim:
http-server db-client app-server mysql-server
Consulte alterações de metadados usando o recurso wait-for-change
Os valores de metadados podem mudar durante a execução da VM. Por isso, o
servidor de metadados pode ser notificado sobre alterações de metadados usando o
recurso wait-for-change
. Com essa opção, a solicitação só retornará uma
saída quando os metadados especificados tiverem sido alterados.
Use esse recurso em metadados personalizados ou definidos pelo servidor. Assim, se houver alteração na sua instância ou no seu projeto ou se alguém atualizar um entrada de metadado personalizado, você poderá reagir à alteração programaticamente.
Por exemplo, é possível executar uma
solicitação na chave tags
para que a solicitação seja retornada apenas se o conteúdo dos
metadados das tags tiver sido alterado. Quando a solicitação é respondida, ela retorna o novo valor dessa chave de metadados.
O recurso wait-for-change
também permite fazer correspondência com a solicitação e
definir tempos limites.
Ao trabalhar com o recurso wait-for-change
, considere o seguinte:
Só é possível executar uma solicitação
wait-for-change
em um endpoint de metadados ou de maneira recursiva no conteúdo de um diretório. Não é possível executar uma solicitaçãowait-for-change
em uma listagem de diretórios. Se você tentar fazer isso, o servidor de metadados falhará na solicitação e retornará um erro 400 Solicitação inválida.Não é possível executar uma solicitação
wait-for-change
para um token de conta de serviço. Se você tentar enviar uma solicitaçãowait-for-change
ao URL do token da conta de serviço, ela falhará imediatamente e retornará um erro 400 Solicitação inválida.
Para executar uma solicitação wait-for-change
, consulte uma chave de metadados e anexe o
parâmetro de consulta ?wait_for_change=true
:
Linux
- Conecte-se à VM do Linux.
Na VM do Linux, use a ferramenta
curl
para fazer uma consulta.Para executar uma solicitação
wait-for-change
em uma entrada de metadados da instância de VM, execute o seguinte comando:curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true" -H "Metadata-Flavor: Google"
Para executar uma solicitação
wait-for-change
para uma entrada de metadados do projeto, execute o seguinte comando:curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
Substitua
METADATA_KEY
pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor.
Exemplos
Neste exemplo, se uma solicitação for feita para setInstanceTags method
, a
solicitação retornará com os novos valores:
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"
O resultado será assim:
http-server db-client
Também é possível executar uma solicitação wait-for-change
de maneira recursiva no conteúdo de um
diretório:
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"
Quando houver alterações, o servidor de metadados retorna o novo conteúdo:
{"foo":"bar","baz":"bat"}
Windows
- Conecte-se à VM do Windows:
Na VM do Windows, use o comando
Invoke-RestMethod
para fazer uma consulta.PS C:> $value = (Invoke-RestMethod
-Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/METADATA_KEY?wait_for_change=true") $valuePara executar uma solicitação
wait-for-change
em uma entrada de metadados da instância de VM, execute o seguinte comando:$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true") $value
Para executar uma solicitação
wait-for-change
para uma entrada de metadados do projeto, execute o seguinte comando:$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true") $value
Substitua
METADATA_KEY
pela chave de metadados da instância ou do projeto para a qual você quer executar uma solicitaçãowait-for-change
.Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor.
Exemplos
Depois que a chave de metadados especificada é alterada, a consulta retorna o novo valor. Neste exemplo, se uma solicitação for feita para
setInstanceTags method
, a solicitação retornará com
os novos valores:
PS C:>
$value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
$value
O resultado será assim:
http-server db-client
Também é possível executar uma solicitação wait-for-change
de maneira recursiva no conteúdo de um
diretório:
PS C:>
$value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
$value
Quando houver alterações, o servidor de metadados retorna o novo conteúdo:
{"foo":"bar","baz":"bat"}
Usar ETags
Quando você envia uma consulta wait-for-change
simples, o servidor de metadados retorna uma
resposta se algo tiver sido alterado no conteúdo desses metadados. No entanto,
há uma disputa inerente entre uma atualização de metadados e uma
solicitação wait-for-change
que está sendo emitida. Por isso é útil ter uma maneira confiável
de saber que você está recebendo o valor de metadados mais recente.
Para ajudar com isso, é possível usar o parâmetro de consulta last_etag
, que compara o valor da ETag fornecido com o valor da ETag salvo no servidor de metadados. Se
os valores das ETag corresponderem, a solicitação wait-for-change
será aceita. Caso contrário, isso indica que o conteúdo dos metadados foi alterado após a última recuperação do valor de ETag, e o valor mais recente é retornado imediatamente no servidor de metadados.
VMs do Linux
Para receber o valor atual da ETag de uma chave de metadados, siga estas etapas:
- Conecte-se à VM do Linux.
Faça uma solicitação para essa chave e imprima os cabeçalhos. Para fazer isso, use a ferramenta
curl
com a sinalização-v
:Para receber a ETag atual de uma entrada de metadados da instância de VM, execute o seguinte comando:
curl -v "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
Para receber a ETag atual de uma entrada de metadados do projeto, execute o seguinte comando:
curl -v "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
Substitua
METADATA_KEY
pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.Por exemplo, o comando a seguir recebe o valor atual da ETag para a chave de metadados da instância
tags
.user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
O resultado será assim:
* About to connect() to metadata port 80 (#0) * Trying 169.254.169.254... connected * Connected to metadata (169.254.169.254) port 80 (#0) > GET /computeMetadata/v1/instance/tags HTTP/1.1 > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15 > Host: metadata > Accept: */* > < HTTP/1.1 200 OK < Content-Type: application/text < ETag: 411261ca6c9e654e < Date: Wed, 13 Feb 2013 22:43:45 GMT < Server: Metadata Server for VM < Content-Length: 26 < X-XSS-Protection: 1; mode=block < X-Frame-Options: SAMEORIGIN < http-server db-client
Em seguida, use esse valor de ETag com o comando ferramenta
curl
na sua solicitaçãowait-for-change
:Para usar o valor da ETag para a solicitação
wait-for-change
dos metadados da instância, execute o seguinte comando:curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
Para usar o valor da ETag para a solicitação
wait-for-change
dos metadados do projeto, execute o seguinte comando:curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
Substitua:
METADATA_KEY
: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.ETAG
: o valor da ETag da chave de metadados.
Neste exemplo, o comando a seguir usa o valor da ETag para a chave
tags
e consulta a entrada de metadados da instância.user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"
O servidor de metadados corresponde ao valor da ETag especificado e, se esse valor for alterado, a solicitação retornará com o novo conteúdo da chave de metadados.
VM do Windows
Para receber o valor atual da ETag de uma chave de metadados, siga estas etapas:
- Conecte-se à VM do Windows:
Faça uma solicitação para essa chave e imprima os cabeçalhos. No Windows, use o
Invoke-WebRequest
comando.Para receber a ETag atual de uma entrada de metadados da instância de VM, execute o seguinte comando:
$value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY) $value.Headers.ETag
Para receber a ETag atual de uma entrada de metadados do projeto, execute o seguinte comando:
$value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY) $value.Headers.ETag
Substitua
METADATA_KEY
pela chave de metadados da instância ou do projeto para a qual você quer consultar o valor.Por exemplo, o comando a seguir recebe o valor atual da ETag para a chave de metadados da instância
tags
.PS C:> $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)
$value.Headers.ETag
O resultado será assim:
* About to connect() to metadata port 80 (#0) * Trying 169.254.169.254... connected * Connected to metadata (169.254.169.254) port 80 (#0) > GET /computeMetadata/v1/instance/tags HTTP/1.1 > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15 > Host: metadata > Accept: / > < HTTP/1.1 200 OK < Content-Type: application/text < ETag: 411261ca6c9e654e < Date: Wed, 13 Feb 2013 22:43:45 GMT < Server: Metadata Server for VM < Content-Length: 26 < X-XSS-Protection: 1; mode=block < X-Frame-Options: SAMEORIGIN < http-server db-client
Em seguida, use esse valor de ETag na solicitação
wait-for-change
:Para usar o valor da ETag para a solicitação
wait-for-change
dos metadados da instância, execute o seguinte comando:$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG") $value
Para usar o valor da ETag para a solicitação
wait-for-change
dos metadados do projeto, execute o seguinte comando:$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG") $value
Substitua:
METADATA_KEY
: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.ETAG
: o valor da ETag da chave de metadados.
Neste exemplo, o comando a seguir usa o valor da ETag para a chave
tags
e consulta a entrada de metadados da instância.PS C:> $value = (Invoke-RestMethod
-Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e") $valueO servidor de metadados corresponde ao valor da ETag especificado e, se esse valor for alterado, a solicitação retornará com o novo conteúdo da chave de metadados.
Python
Na amostra de Python a seguir, veja como monitorar o servidor de metadados programaticamente para verificar se houve alterações.
Nesta amostra, a ETag inicial foi definida como 0
. O servidor de metadados não retornará uma resposta com 0
como o valor da ETag. Quando 0
for especificado como a última ETag
em uma solicitação, o servidor de metadados responderá com o valor atual e a ETag. Isso poupa um pouco do código necessário para conseguir o valor e a ETag iniciais.
Definir limites de tempo
Se você quiser que a solicitação wait-for-change
expire após um determinado
número de segundos, defina o parâmetro timeout_sec
. O parâmetro timeout_sec
limita o tempo de espera da solicitação ao número de segundos especificado
e, quando a solicitação atinge esse limite,
retorna o conteúdo atual da chave de metadados.
Quando você define o parâmetro timeout_sec
, a solicitação sempre retorna após o número especificado de segundos, independentemente de o valor dos metadados ter sido alterado ou não. O tempo limite só pode ser definido com um valor inteiro.
Linux
- Conecte-se à VM do Linux.
Na VM do Linux, use a ferramenta
curl
para fazer uma consulta.Para executar uma solicitação
wait-for-change
com um valor de tempo limite para uma entrada de metadados da instância de VM, execute o seguinte comando:curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
Para executar uma solicitação
wait-for-change
com um valor de tempo limite para uma entrada de metadados do projeto, execute o seguinte comando:curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
Substitua:
METADATA_KEY
: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.TIMEOUT
: o valor de tempo limite.
Por exemplo, o comando a seguir executa uma solicitação wait-for-change
configurada
para expirar após 360 segundos:
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"
Windows
- Conecte-se à VM do Windows:
Na VM do Windows, use o comando
Invoke-RestMethod
para fazer uma consulta.Para executar uma solicitação
wait-for-change
com um valor de tempo limite para uma entrada de metadados da instância de VM, execute o seguinte comando:$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT") $value
Para executar uma solicitação
wait-for-change
com um valor de tempo limite para uma entrada de metadados do projeto, execute o seguinte comando:$value = (Invoke-RestMethod ` -Headers @{'Metadata-Flavor' = 'Google'} ` -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT") $value
Substitua:
METADATA_KEY
: a chave de metadados da instância ou do projeto para a qual você quer consultar o valor.TIMEOUT
: o valor de tempo limite.
Por exemplo, o comando a seguir executa uma solicitação wait-for-change
configurada
para expirar após 360 segundos:
PS C:>
$value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
$value
Códigos de status
Quando você executa uma solicitação wait-for-change
, o servidor de metadados retorna códigos de
status HTTP padrão para indicar se houve sucesso ou falha. Em caso de erros, as condições da rede podem fazer com que a sua solicitação seja cancelada e um código de erro seja retornado pelo servidor de metadados. Se esse for o caso, desenvolva seu aplicativo para ser tolerante a falhas, reconhecer e tratar esses erros.
Os seguintes status podem ser retornados pelo servidor de metadados:
Status | Descrição |
---|---|
HTTP 200 |
Pronto. Um valor foi alterado ou você atingiu o valor especificado timeout_sec e a solicitação
foi retornada.
|
Error 400 |
A solicitação não era válida. Corrija a sua consulta e tente fazer a solicitação novamente. |
Error 404 |
O valor de metadados especificado não existe mais. Esse erro também é retornado no servidor de metadados se os metadados foram excluídos enquanto você aguardava uma alteração. |
Error 503 |
Ocorreu um erro temporário de servidor ou um evento temporário de manutenção. Tente fazer a solicitação novamente. |
Limitações
Todas as solicitações com o cabeçalho
X-Forwarded-For
são automaticamente rejeitadas pelo servidor de metadados. Isso ocorre porque, em geral, esse cabeçalho é usado para indicar que a solicitação foi enviada por proxy, ou seja, talvez ela não tenha sido feita por um usuário autorizado. Por motivos de segurança, todas as solicitações desse tipo são rejeitadas.Quando você usa o comando
curl
para recuperar metadados do servidor, observe que alguns caracteres codificados não são aceitos no caminho da solicitação. Caracteres codificados são aceitos apenas no caminho da consulta.Por exemplo, esta solicitação pode não funcionar:
curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"
Para que ela funcione, substitua o caractere codificado não aceito no caminho da solicitação (
%40
) pelo valor equivalente aceito (@
).curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"
A tabela a seguir resume os caracteres codificados que não são aceitos em um caminho de solicitação.
Caractere codificado Valor aceito %21 !
%24 $
%27 '
%28 (
%29 )
%2A *
%2C ,
%40 @
Conferir os metadados personalizados das suas VMs
É possível visualizar os valores de metadados personalizados para suas VMs do Compute Engine de uma das seguintes maneiras:
- Ver metadados de todo o projeto
- Ver metadados zonais do projeto (Pré-lançamento)
- Ver metadados da instância
Ver metadados de todo o projeto
Para ver metadados personalizados que se aplicam a todas as VMs no projeto, use um dos métodos a seguir.
Console
No Console do Google Cloud, acesse a página Metadados.
- Na guia Metadados, é possível analisar a maioria dos metadados personalizados do projeto, com exceção dos metadados de chave SSH.
- Na guia Chaves SSH, é possível revisar todos os metadados de chave SSH no nível do projeto.
gcloud
Use o
comando gcloud compute project-info describe
para consultar os metadados do projeto:
gcloud compute project-info describe --flatten="commonInstanceMetadata[]"
O resultado será assim:
--- fingerprint: HcSFdS_1_1I= items: - key: ssh-keys value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ... kind: compute#metadata
REST
Para consultar os metadados do projeto, crie uma solicitação GET
para o
método project.get
.
Substitua PROJECT_ID
pelo ID do projeto.
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
O resultado será assim:
"kind": "compute#project", "id": "XXXXXXX", "creationTimestamp": "2018-12-10T08:34:33.616-08:00", "name": "YOUR_PROJECT", "commonInstanceMetadata": { "kind": "compute#metadata", "fingerprint": "XXXXXCdg=", "items": [ { "key": "enable-guest-attributes", "value": "TRUE" }, { "key": "enable-os-inventory", "value": "true" }, { "key": "enable-osconfig", "value": "TRUE" }, { "key": "enable-oslogin", "value": "TRUE" }, { "key": "sshKeys", "value": "XXXXX" } ] }, ...
Ver metadados zonais do projeto
Para ver metadados personalizados que se aplicam a todas as instâncias de VM em uma zona específica em um projeto, use um dos métodos a seguir.
gcloud
Para consultar os metadados personalizados zonais do projeto, use o
comando gcloud beta compute project-zonal-metadata describe
.
gcloud beta compute project-zonal-metadata describe \ --zone=ZONE \ --project=PROJECT_ID
Substitua:
PROJECT_ID
: ID do projeto;ZONE
: a zona em que você quer visualizar os metadados zonais do projeto.
O resultado será assim:
{ "fingerprint": "VlRIl8dx9vk=", "metadata": { items: { "key-1": "value-1", "key-2": "value-2" } } }
REST
Para consultar os metadados personalizados zonais do projeto, faça uma solicitação GET
para o
método instanceSettings().get
GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
Substitua:
PROJECT_ID
: ID do projeto;ZONE
: a zona em que você quer visualizar os metadados zonais do projeto.
O resultado será assim:
{ "fingerprint": "VlRIl8dx9vk=", "metadata": { items: { "key-1": "value-1", "key-2": "value-2" } } }
Ver metadados da instância
Para ver metadados personalizados que se aplicam a uma única VM no projeto, use um dos métodos a seguir.
Console
- No console do Google Cloud, acesse a página Instâncias de VMs.
Clique no nome da VM com os metadados que você quer ver.
Chaves SSH para esta VM. Na seção Segurança e acesso, veja o campo Chaves SSH.
Um valor
None
indica que não há chaves SSH armazenadas nos metadados da instância.Qualquer outro valor indica que há chaves SSH armazenadas nos metadados da instância.
Chaves SSH de um projeto. Na seção Segurança e acesso, veja o campo Bloquear chaves SSH do projeto inteiro.
Um valor de
On
indica que o valor da chave de metadadosblock-project-ssh-keys
éTRUE
nos metadados da instância.Um valor de
Off
indica que o valor da chave de metadadosblock-project-ssh-keys
éFALSE
ou que a chave não está definida.
Todos os outros metadados personalizados. Veja a seção Metadados personalizados. Você verá todos os valores e chaves de metadados personalizados, exceto metadados de chave SSH.
gcloud
Use o
comando gcloud compute instances describe
para consultar os metadados da instância:
gcloud compute instances describe VM_NAME --flatten="metadata[]"
Substitua VM_NAME
pelo nome da VM que você quer encontrar os metadados.
O resultado será assim:
--- fingerprint: MTgTJ5m-Cjs= items: - key: enable-oslogin value: 'true' kind: compute#metadata
REST
Para consultar metadados de uma VM específica, envie uma solicitação GET
para o
método instances.get
.
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
O resultado será assim:
...... "metadata": { "kind": "compute#metadata", "fingerprint": "XXXXXXVo=", "items": [ { "key": "enable-oslogin", "value": "true" } ] },....
Substitua:
PROJECT_ID
: ID do projeto;ZONE
: é a zona em que a VM está localizadaVM_NAME
: o nome da VM
A seguir
- Saiba mais sobre os metadados da VM.
- Saiba como definir metadados personalizados.
- Saiba como definir e consultar atributos de convidado.