Este documento describe cómo construir solicitudes API y manejar respuestas API desde la API de Compute Engine. Cubre cómo:
- Construya un cuerpo de solicitud.
- Determine los URI de recursos necesarios para una solicitud.
- Manejar respuestas API.
- Determine si una solicitud de API se realizó correctamente.
Este documento no cubre cómo autenticarse en la API. Para aprender cómo autenticarse en la API, lea Autenticarse en Compute Engine .
Antes de comenzar
- Familiarícese con las API REST .
- Sepa cómo autenticarse en la API de Compute Engine.
Creando una solicitud API
La API de Compute Engine espera que las solicitudes de API estén en formato JSON. Para realizar una solicitud de API, puede realizar una solicitud HTTP directa mediante herramientas como curl
o httplib2
, o puede utilizar una de las bibliotecas cliente disponibles .
Cuando realiza una solicitud de API que requiere un cuerpo de solicitud, como una solicitud POST
, UPDATE
o PATCH
, el cuerpo de la solicitud contiene propiedades de recursos que desea establecer en esta solicitud. Por ejemplo, el siguiente comando curl
realiza una solicitud POST
al URI del recurso de Instancias. La solicitud crea una instancia con las propiedades definidas en el cuerpo de la solicitud. El cuerpo de la solicitud se indica con el indicador -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" } ] }'
El URI de la imagen tiene un ID de proyecto diferente ( debian-cloud
) del ID de su proyecto porque las imágenes pertenecen a proyectos diferentes, según el tipo de imagen. Por ejemplo, todas las imágenes de Debian disponibles públicamente que ofrece Compute Engine están alojadas en el proyecto debian-cloud
.
Cuando haga referencia a otro recurso, utilice el URI de recurso completo. Por ejemplo, la propiedad network
utiliza un URI completo para la red default
.
Ejemplos de solicitudes de API
Pitón
Java
Crear URI de recursos
En la API de Compute Engine, una referencia a otro Google Cloud El recurso se proporciona como un URI completamente calificado:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/SPECIFIC_RESOURCE
Siempre que especifique una imagen, un tipo de máquina, una red o cualquier otro recurso, debe proporcionar el URI del recurso cuando utilice la API. Las herramientas cliente como la CLI de Google Cloud y la consola de Google Cloud ocultan esta complejidad y se encargan de crear estos URI de recursos por usted, pero al interactuar directamente con la API, debe crear estos URI de recursos usted mismo.
Hay URI de recursos ligeramente diferentes para diferentes tipos de recursos. Por ejemplo, un recurso zonal tiene la especificación zone
en el URI:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2
Los recursos regionales reemplazan la especificación zone
con una especificación region
:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME
De manera similar, los recursos globales tienen la especificación global
:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/VM_NAME
La API de Compute Engine también acepta URI parciales porque el servicio puede inferir información como el ID del proyecto. Por lo tanto, las siguientes versiones parciales de los URI anteriores también son aceptables:
zones/ZONE/machineTypes/e2-standard-2
regions/REGION/addresses/ADDRESS_NAME
project/PROJECT_ID/global/images/VM_NAME
En los URI parciales, tanto el URI zonal como el regional omitieron el ID del proyecto, pero el URI de la imagen no. Esto se debe a que las imágenes disponibles públicamente que ofrece Compute Engine están alojadas en otros proyectos, como debian-cloud
para todas las imágenes de Debian y ubuntu-os-cloud
para todas las imágenes de Ubuntu. Antes de poder utilizar estas imágenes, debe proporcionar el ID del proyecto adecuado. Si omites el ID del proyecto para las imágenes, Compute Engine intenta encontrar la imagen en tu proyecto y la solicitud falla porque la imagen no existe.
Sin embargo, si utiliza una imagen personalizada que pertenece a su proyecto (el mismo proyecto en el que está creando este recurso), puede omitir la especificación del proyecto al proporcionar un URI de imagen.
Determinar las propiedades requeridas
La documentación de referencia de la API de Compute Engine, disponible para las API v1 y beta , describe todas las propiedades posibles que puede configurar para un recurso específico. La documentación de referencia hace una distinción entre propiedades mutables e inmutables (marcadas con [Output Only]
en la descripción de la propiedad), pero para determinar las propiedades requeridas para un recurso, debe revisar la documentación específica de esa tarea.
Por ejemplo, si está creando una instancia, lea la documentación Creación de una instancia a partir de una imagen para ver las propiedades de API necesarias para la solicitud. Si desea crear una dirección IP externa estática en la API, lea la documentación sobre Direcciones IP externas estáticas .
Validar solicitudes de API
Para validar sus solicitudes de API:
- En la referencia de la API de Compute Engine , busca el método que llama tu código. Por ejemplo,
v1/compute.instances.insert
. En el menú de contenidos, haz clic en ¡Pruébalo! Esto abre la ventana Pruebe esta API .
En Parámetros de solicitud , no es necesario proporcionar un proyecto o zona porque la validación no requiere enviar la solicitud.
En Cuerpo de la solicitud , pegue su solicitud.
Los elementos mal formados de la solicitud están subrayados en azul. Haga clic en cada sección subrayada para obtener más información sobre el problema que se va a abordar.
Manejo de respuestas API
Si realizas una solicitud que muta (altera) datos, Compute Engine devuelve un objeto Operation
que luego puedes sondear para obtener el estado de las operaciones de tu solicitud. El recurso Operation
se ve así:
{ "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" }
Si la solicitud original es mutar (alterar) un recurso zonal (por ejemplo, tomar una instantánea de un disco o detener una instancia), Compute Engine devuelve un objeto zoneOperations
. De manera similar, los recursos regionales y globales devuelven un objeto regionOperations
o globalOperations
, respectivamente. Puede obtener el estado de una operación realizando una solicitud que utilice el método get
o wait
para el recurso Operation
específico y proporcionando el name
de la operación.
Su solicitud no estará completa hasta que el estado del recurso Operation
vuelva a ser DONE
. Esto puede llevar algún tiempo dependiendo de la naturaleza de su solicitud. Luego, después de que el estado del recurso Operation
regrese a DONE
, puede verificar si la operación se realizó correctamente y si hubo algún error.
Por ejemplo, la siguiente respuesta indica que la operación anterior ya está completa, especificada por el estado 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, realice una solicitud get
al recurso para comprobar que existe y se está ejecutando. Por ejemplo:
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" }
Operaciones de sondeo
Puede escribir código para sondear periódicamente la operación con una solicitud get
o wait
que regresa cuando el estado de la operación es DONE
.
Con una solicitud get
, la operación se devuelve inmediatamente, independientemente del estado de la operación. Debe sondear la operación periódicamente para saber cuándo finaliza.
Si realiza una solicitud wait
, la solicitud regresa cuando la operación esté DONE
o si la solicitud se acerca al plazo de 2 minutos. Puede optar por utilizar wait
o get
para sondear sus operaciones, pero el método wait
proporciona ciertos beneficios sobre el método get
:
- Puedes configurar tus clientes para que sondeen el estado de la operación con menos frecuencia, lo que reduce el uso de QPS de la API de Compute Engine.
- La latencia promedio entre el momento en que se realiza la operación y el momento en que se informa al cliente que la operación se realiza se reduce significativamente porque el servidor responde tan pronto como se realiza la operación.
- El método proporciona esperas limitadas. El método no espera más que el tiempo de espera HTTP predeterminado (2 minutos) y luego devuelve el estado actual de la operación, que puede estar
DONE
o aún en progreso.
El método wait
es una API de mejor esfuerzo . Si el servidor está sobrecargado, la solicitud podría regresar antes de que llegue la fecha límite predeterminada o después de esperar cero segundos. Tampoco se garantiza que el método regrese solo cuando la operación esté DONE
. Por ejemplo, si la solicitud se acerca al plazo de 2 minutos, el método regresa incluso si la operación no se realiza. Para comprobar sus operaciones, le recomendamos que utilice el método wait
o get
(en un ciclo de reintento con suspensión intermedia) para sondear periódicamente el estado de la operación. El intervalo máximo de reintento no debe exceder el período mínimo de retención de la operación .
Ejemplo de encuesta
Los siguientes ejemplos utilizan el método get
. Puedes reemplazar el método get
con el método wait
: