En este documento, se describen las prácticas recomendadas para usar la API de Compute Engine y está dirigido a usuarios que ya están familiarizados con ella. Si eres principiante, obtén más información sobre los requisitos previos y cómo usar la API de Compute Engine.
Seguir estas prácticas recomendadas puede ayudarte a ahorrar tiempo, evitar errores y mitigar los efectos de las cuotas de frecuencia.
Usar las bibliotecas cliente
Las bibliotecas cliente son la forma recomendada de acceder de manera programática a la API de Compute Engine. Las bibliotecas cliente proporcionan un código que te permite acceder a la API a través de lenguajes de programación comunes, lo que puede ahorrarte tiempo y mejorar el rendimiento de tu código.
Obtén más información sobre las bibliotecas cliente de Compute Engine y las prácticas recomendadas de la biblioteca cliente.
Genera solicitudes de REST mediante la consola de Cloud
Cuando crees un recurso, genera la solicitud de REST mediante las páginas de creación de recursos o las páginas de detalles en la consola de Google Cloud. El uso de una solicitud de REST generada ahorra tiempo y ayuda a evitar errores de sintaxis.
Aprende a generar solicitudes de REST.
Espera a que se completen las operaciones
No supongas que una operación (cualquier solicitud a la API que cambia un recurso) está completa o se realizó correctamente. En su lugar, usa un método wait para el recurso Operation a fin de verificar que se haya completado la operación. No necesitas verificar una solicitud que no modifica los recursos, como una solicitud de lectura mediante un verbo HTTP GET, porque la respuesta de la API ya indica si la solicitud se realizó correctamente. En consecuencia, la API de Compute Engine no muestra los recursos Operation para estas solicitudes.
Cada vez que se inicia una solicitud a la API de forma correcta, se muestra un código de estado HTTP 200. Aunque recibir un 200 indica que el servidor recibió tu solicitud a la API de forma correcta, este código de estado no indica si la operación solicitada se completó correctamente o no. Por ejemplo, puedes recibir un 200, pero es posible que la operación aún no se haya completado o que falle.
Cualquier solicitud para crear, actualizar o borrar una operación de larga duración muestra un recurso Operation, que captura el estado de esa solicitud. Una operación se realiza cuando el campo status del recurso Operation es DONE. Para verificar el estado, usa el método wait que coincida con el alcance del recurso Operation que se muestra:
- Para operaciones zonales, usa
zoneOperations.wait. - Para operaciones regionales, usa
regionOperations.wait. - Para operaciones globales, usa
globalOperations.wait.
El método wait se muestra cuando se completa la operación o cuando la solicitud se acerca al plazo de 2 minutos. Cuando uses el método wait, evita los sondeos cortos, que son cuando tus clientes realizan solicitudes al servidor de forma continua sin esperar una respuesta. Usa el método wait en un bucle de
reintentos con retirada exponencial para verificar el
estado de la solicitud (en lugar de usar el método get con sondeos cortos
para el recurso Operation) ayuda a preservar tus cuotas de frecuencia
y reduce la latencia.
Para obtener más información y ejemplos de uso del método wait, consulta Cómo manejar respuestas de la API.
Para verificar el estado de una operación solicitada, consulta Verifica el estado de la operación.
Mientras esperas a que se complete una operación, ten en cuenta el período de retención mínimo de la operación, ya que las operaciones completadas se pueden quitar de la base de datos después de este período.
Muestra una lista paginada de resultados
Cuando uses un método de lista (como un método *.list, un método *.aggregatedList o cualquier otro método que muestre una lista), pagina los resultados siempre que sea posible para garantizar que leas la respuesta completa. Si no usas la paginación, solo puedes recibir hasta los primeros 500 elementos según lo determinado por el parámetro de consulta maxResults.
Para obtener más información sobre la paginación en Google Cloud, consulta Paginación de listas.
Para obtener detalles y ejemplos específicos, consulta la documentación de referencia del método de lista que deseas usar, como instances.list.
También puedes usar las bibliotecas cliente de Cloud para controlar la paginación.
Usa filtros de listas del cliente para evitar errores de cuotas
Cuando usas filtros con los métodos *.list o *.aggregatedList, se generan
cargos de cuota adicionales si hay más de 10,000 recursos filtrados de las
solicitudes.
Para obtener más información, consulta filtered_list_cost_overhead
en Cuotas de tarifas.
Si tu proyecto excede una cuota de frecuencia, recibirás un error 403 con el motivo rateLimitExceeded. A fin de evitar este error,
usa filtros de cliente para las solicitudes de lista.
Confía en los códigos de error, no en los mensajes de error
Las API de Google deben usar los códigos de error canónicos definidos por google.rpc.Code, pero los mensajes de error pueden estar sujetos a cambios sin previo aviso. Por lo general, el objetivo de los mensajes de error es que los lean los desarrolladores, no los programas.
Más información sobre los errores relacionados con las API
Minimiza los reintentos del cliente para preservar las cuotas de frecuencia
Minimiza la cantidad de reintentos del cliente en un proyecto para evitar
errores de rateLimitExceeded y maximizar el uso de las
cuotas de frecuencia. Las siguientes prácticas
pueden ayudarte a preservar las cuotas de frecuencia para tus proyectos:
- Evita los sondeos cortos.
- Usa bursting de forma moderada y selectiva.
- Siempre realiza tus llamadas en un bucle de reintento con retirada exponencial.
- Usa un limitador de frecuencia del cliente.
- Divide tus aplicaciones en varios proyectos.
Evita los sondeos cortos
Evita los sondeos cortos, en los que los clientes realizan solicitudes al servidor de forma continua sin esperar una respuesta. Si realizas un sondeo corto, será más difícil detectar solicitudes erróneas que se tengan en cuenta en tu cuota, incluso si no muestran datos útiles.
En lugar de sondeos cortos, debes esperar a que se realicen las operaciones.
Usa los aumentos de actividad de forma moderada y selectiva
Usa bursting de forma moderada y selectiva. Los aumentos de actividad son el acto de permitir que un cliente específico haga muchas solicitudes a la API en un período corto de tiempo. Por lo general, esto se hace en casos excepcionales, como cuando tu aplicación necesita manejar más tráfico de lo habitual. Los aumentos de actividad harán que se llegue rápidamente a tu cuota de tarifa, así que asegúrate de usarlos solo cuando sea necesario.
Cuando sea necesario usar los aumentos de actividad, usa API de lotes dedicadas cuando sea posible, como la API de instancia masiva o los grupos de instancias administrados.
Obtén más información para agrupar solicitudes en lotes.
Realiza siempre tus llamadas en un bucle de reintentos con retirada exponencial
Usa la retirada exponencial para espaciar las solicitudes de forma progresiva cuando se agote el tiempo de espera o cuando alcances tu cuota de frecuencia.
Cualquier bucle de reintento debe tener una retirada exponencial que garantice que los reintentos frecuentes no sobrecarguen tu aplicación ni excedan tus cuotas de frecuencia. De lo contrario, corres el riesgo de afectar todos los demás sistemas del mismo proyecto.
Si necesitas un bucle de reintento para una operación que falló porque alcanzaste la cuota de frecuencia, la estrategia de retirada exponencial debe permitir tiempo suficiente entre los reintentos para que se vuelva a completar el bucket de cuota (por lo general, cada minuto).
De forma alternativa, si necesitas un bucle de reintento para cuando espera a que una operación
alcance el tiempo de espera, el intervalo máximo de la estrategia de retirada exponencial
no debe exceder el período de retención mínimo de la operación. De lo contrario, es posible
que recibas un error Not Found de operación.
Para ver un ejemplo de implementación de la retirada exponencial, consulta el algoritmo de retirada exponencial de la API de Identity and Access Management.
Usa un limitador de frecuencia del cliente.
Usa un limitador de frecuencia del cliente. Un limitador de frecuencia del cliente establece un límite artificial para que el cliente en cuestión solo pueda usar una determinada cantidad de cuota, lo que evita que cualquier cliente consuma toda tu cuota.
Divide tus aplicaciones en varios proyectos
Dividir las aplicaciones en varios proyectos puede ayudar a minimizar la cantidad de solicitudes para los buckets de cuota. Dado que las cuotas se aplican en un nivel por proyecto, puedes dividir tus aplicaciones para que cada una tenga su propio bucket de cuota dedicado.
Resumen de la lista de tareas
En la siguiente lista de tareas, se resumen las prácticas recomendadas para el uso de la API de Compute Engine.
- Usar las bibliotecas cliente
- Genera solicitudes de REST con la consola de Cloud
- Esperar a que se realicen las operaciones
- Mostrar una lista paginada de resultados
- Confiar en los códigos de error, no en los mensajes de error
- Minimiza los reintentos del cliente para preservar los límites de frecuencia de la API