Este documento descreve como criar solicitações de API e processar respostas de API da API Compute Engine. Abrange como:
- Construa um corpo de solicitação.
- Determine os URIs de recursos necessários para uma solicitação.
- Lidar com respostas da API.
- Determine se uma solicitação de API foi bem-sucedida.
Este documento não aborda como autenticar na API. Para saber como se autenticar na API, leia Autenticar no Compute Engine .
Antes de começar
- Familiarize-se com APIs REST .
- Saiba como se autenticar na API Compute Engine.
Criando uma solicitação de API
A API Compute Engine espera que as solicitações de API estejam no formato JSON. Para fazer uma solicitação de API, você pode fazer uma solicitação HTTP direta, usando ferramentas como curl
ou httplib2
, ou pode usar uma das bibliotecas cliente disponíveis .
Quando você faz uma solicitação de API que requer um corpo de solicitação, como uma solicitação POST
, UPDATE
ou PATCH
, o corpo da solicitação contém propriedades de recursos que você deseja definir nessa solicitação. Por exemplo, o comando curl
a seguir faz uma solicitação POST
para o URI de recurso de instâncias. A solicitação cria uma instância com as propriedades definidas no corpo da solicitação. O corpo da solicitação é indicado pelo sinalizador -d
:
curl -X POST -H "Authorization: Bearer [OAUTH_TOKEN]" -H "Content-Type: application/json" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances -d '{ "disks":[ { "boot":"true", "initializeParams":{ "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-10-buster-v20210122" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2", "name":"VM_NAME", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default" } ] }'
O URI da imagem possui um ID de projeto diferente ( debian-cloud
) do ID do seu projeto porque as imagens pertencem a projetos diferentes, dependendo do tipo de imagem. Por exemplo, todas as imagens Debian disponíveis publicamente oferecidas pelo Compute Engine são hospedadas no projeto debian-cloud
.
Ao fazer referência a outro recurso, utilize o URI de recurso totalmente qualificado. Por exemplo, a propriedade network
utiliza um URI totalmente qualificado para a rede default
.
Exemplos de solicitações de API
Pitão
Java
Criando URIs de recursos
Na API Compute Engine, uma referência a outro Google Cloud O recurso é fornecido como um URI totalmente qualificado:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/SPECIFIC_RESOURCE
Sempre que você especificar uma imagem, um tipo de máquina, uma rede ou qualquer outro recurso, deverá fornecer o URI ao recurso ao usar a API. Ferramentas de cliente como a CLI do Google Cloud e o console do Google Cloud ocultam essa complexidade e cuidam da criação desses URIs de recursos para você, mas ao interagir diretamente com a API, você mesmo deve criar esses URIs de recursos.
Existem URIs de recursos ligeiramente diferentes para diferentes tipos de recursos. Por exemplo, um recurso zonal possui a especificação zone
no URI:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2
Os recursos regionais substituem a especificação zone
por uma especificação region
:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME
Da mesma forma, os recursos globais têm a especificação global
:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/VM_NAME
A API Compute Engine também aceita URIs parciais porque o serviço pode inferir informações como o ID do projeto. Portanto, as seguintes versões parciais dos URIs anteriores também são aceitáveis:
zones/ZONE/machineTypes/e2-standard-2
regions/REGION/addresses/ADDRESS_NAME
project/PROJECT_ID/global/images/VM_NAME
Nos URIs parciais, tanto os URIs zonais quanto os regionais omitiram o ID do projeto, mas o URI da imagem não. Isso ocorre porque as imagens disponíveis publicamente oferecidas pelo Compute Engine são hospedadas em outros projetos, como debian-cloud
para todas as imagens do Debian e ubuntu-os-cloud
para todas as imagens do Ubuntu. Antes de poder usar essas imagens, você precisa fornecer o ID do projeto apropriado. Se você omitir o ID do projeto para imagens, o Compute Engine tentará encontrar a imagem no seu projeto, e a solicitação falhará porque a imagem não existe.
No entanto, se você usar uma imagem personalizada que pertence ao seu projeto (o mesmo projeto no qual você está criando esse recurso), poderá omitir a especificação do projeto ao fornecer um URI de imagem.
Determinando propriedades necessárias
A documentação de referência da API Compute Engine, disponível para APIs v1 e beta , descreve todas as propriedades possíveis que você pode definir para um recurso específico. A documentação de referência faz uma distinção entre propriedades mutáveis e imutáveis (marcadas por [Output Only]
na descrição da propriedade), mas para determinar as propriedades necessárias para um recurso, é necessário revisar a documentação específica para essa tarefa.
Por exemplo, se você estiver criando uma instância, leia a documentação Criando uma instância a partir de uma imagem para ver as propriedades da API necessárias para a solicitação. Se você deseja criar um endereço IP externo estático na API, leia a documentação Endereços IP externos estáticos .
Validando solicitações de API
Para validar suas solicitações de API:
- Na referência da API Compute Engine , encontre o método que seu código está chamando. Por exemplo,
v1/compute.instances.insert
. No menu de conteúdo, clique em Experimente! Isso abre a janela Experimente esta API .
Em Parâmetros de solicitação , você não precisa fornecer um projeto ou zona porque a validação não exige o envio da solicitação.
Em Request body , cole sua solicitação.
Os elementos malformados da solicitação estão sublinhados em azul. Clique em cada seção sublinhada para obter mais informações sobre o problema a ser abordado.
Tratamento de respostas da API
Se você fizer uma solicitação que altere (altere) os dados, o Compute Engine retornará um objeto Operation
que você poderá pesquisar para obter o status das operações da sua solicitação. O recurso Operation
é assim:
{ "kind": "compute#operation", "id": "7127550864823803662", "name": "operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b", "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE", "operationType": "insert", "targetLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM", "targetId": "4132355614508179214", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2016-03-24T14:53:37.788-07:00", "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b" }
Se a solicitação original for para modificar (alterar) um recurso zonal (por exemplo, para capturar um instantâneo de um disco ou interromper uma instância), o Compute Engine retornará um objeto zoneOperations
. Da mesma forma, os recursos regionais e globais retornam um objeto regionOperations
ou globalOperations
, respectivamente. Você pode obter o status de uma operação executando uma solicitação que usa o método get
ou wait
para o recurso Operation
específico e fornecendo o name
da operação.
Sua solicitação não será concluída até que o status do recurso Operation
retorne como DONE
. Isso pode levar algum tempo dependendo da natureza da sua solicitação. Então, depois que o status do recurso Operation
retornar como DONE
, você poderá verificar se a operação foi bem-sucedida e se houve algum erro.
Por exemplo, a resposta a seguir indica que a operação anterior foi concluída, especificada pelo status DONE
:
endTime: '2016-03-24T14:54:07.119-07:00' id: '7127550864823803662' insertTime: '2016-03-24T14:53:37.788-07:00' kind: compute#operation name: operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b operationType: insert progress: 100 selfLink: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b startTime: '2016-03-24T14:53:38.397-07:00' status: DONE targetId: '4132355614508179214' targetLink: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM user: user@example.com zone: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE
Para confirmar, faça uma solicitação get
ao recurso para verificar se ele existe e está em execução. Por exemplo:
GET /compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM { "cpuPlatform": "Intel Haswell", "creationTimestamp": "2016-03-24T14:53:37.170-07:00", "disks": [ ..[snip].. "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM", "status": "RUNNING", "tags": { "fingerprint": "42WmSpB8rSM=" }, "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE" }
Operações de votação
Você pode escrever algum código para pesquisar periodicamente a operação com uma solicitação get
ou wait
que retorna quando o status da operação for DONE
.
Com uma solicitação get
, a operação é retornada imediatamente, independentemente do status da operação. Você precisa pesquisar a operação periodicamente para saber quando a operação é concluída.
Se você fizer uma solicitação wait
, a solicitação retornará quando a operação for DONE
ou se a solicitação estiver se aproximando do prazo de 2 minutos. Você pode optar por usar wait
ou get
para pesquisar suas operações, mas o método wait
oferece alguns benefícios em relação ao método get
:
- Você pode configurar seus clientes para pesquisar o status da operação com menos frequência, reduzindo o uso de QPS da API Compute Engine.
- A latência média entre o momento em que a operação é concluída e o momento em que o cliente é informado de que a operação foi concluída é significativamente reduzida porque o servidor responde assim que a operação é concluída.
- O método fornece esperas limitadas. O método não espera mais do que o tempo limite HTTP padrão (2 minutos) e então retorna o estado atual da operação, que pode ser
DONE
ou ainda em andamento.
O método wait
é uma API de melhor esforço . Se o servidor estiver sobrecarregado, a solicitação poderá retornar antes de atingir o prazo padrão ou após esperar apenas zero segundos. Também não é garantido que o método retorne apenas quando a operação for DONE
. Por exemplo, se a requisição se aproximar do prazo de 2 minutos, o método retornará mesmo que a operação não seja realizada. Para verificar suas operações, recomendamos que você use o método wait
ou get
— em um loop de nova tentativa com suspensão intermediária — para pesquisar periodicamente o status da operação. O intervalo máximo de novas tentativas não deve exceder o período mínimo de retenção da operação .
Exemplo de pesquisa
Os exemplos a seguir usam o método get
. Você pode substituir o método get
pelo método wait
: