En este documento se describen las prácticas recomendadas para usar la API de Compute Engine y está dirigido a usuarios que ya la conocen. Si eres principiante, consulta los requisitos previos y cómo usar la API de Compute Engine.
Si sigues estas prácticas recomendadas, podrás ahorrar tiempo, evitar errores y mitigar los efectos de las cuotas de frecuencia.
Usar bibliotecas de cliente
Las bibliotecas de cliente son la forma recomendada de acceder a la API de Compute Engine mediante programación. Las bibliotecas de cliente proporcionan 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.
Consulta más información sobre las bibliotecas de cliente de Compute Engine y las prácticas recomendadas para bibliotecas de cliente.
Generar solicitudes REST mediante la consola de Cloud
Cuando crees un recurso, genera la solicitud REST mediante las páginas de creación o de detalles de recursos de la consola Google Cloud . Usar una solicitud REST generada ahorra tiempo y ayuda a evitar errores de sintaxis.
Consulta cómo generar solicitudes REST.
Esperar a que se completen las operaciones
No supongas que una operación (cualquier solicitud a la API que cambie un recurso) se ha completado o se ha realizado correctamente. En su lugar, usa un método wait para el recurso Operation para verificar que la operación se ha completado. No es necesario verificar una solicitud que no modifique recursos (como una solicitud de lectura que utilice un verbo HTTP GET), ya que la respuesta de la API ya indica si la solicitud se ha completado correctamente. Por lo tanto, la API de Compute Engine no devuelve recursos Operation para estas solicitudes.
Cada vez que se inicia correctamente una solicitud a la API, se devuelve un código de estado HTTP 200. Aunque el código 200 indica que el servidor ha recibido correctamente tu solicitud de la API, este código de estado no indica si la operación solicitada se ha completado correctamente o no. Por ejemplo, puedes recibir un 200, pero es posible que la operación aún no se haya completado o que haya fallado.
Cualquier solicitud para crear, actualizar o eliminar una operación de larga duración devuelve un recurso Operation, que registra el estado de esa solicitud. Una operación se completa cuando el campo status del recurso Operation es DONE. Para comprobar el estado, usa el método wait que coincida con el ámbito del recurso Operation devuelto:
- En el caso de las operaciones zonales, usa
zoneOperations.wait. - Para las operaciones regionales, usa
regionOperations.wait. - Para las operaciones globales, usa
globalOperations.wait.
El método wait devuelve un valor cuando se completa la operación o cuando la solicitud se acerca al plazo de 2 minutos. Cuando uses el método wait, evita el sondeo corto, que se produce cuando tus clientes envían solicitudes continuamente al servidor sin esperar una respuesta. Usar el método wait en un bucle de reintentos con retroceso exponencial para comprobar el estado de tu solicitud, en lugar de usar el método get con sondeo corto para el recurso Operation, ayuda a conservar tus cuotas de frecuencia y reduce la latencia.
Para obtener más información y ejemplos sobre el uso del método wait, consulta Gestionar respuestas de la API.
Para comprobar el estado de una operación solicitada, consulta Comprobar el estado de las operaciones.
Mientras esperas a que se complete una operación, ten en cuenta el periodo de conservación mínimo de la operación, ya que las operaciones completadas se pueden eliminar de la base de datos después de este periodo.
Paginación de los resultados de la lista
Cuando uses un método de lista (como un método *.list, un método *.aggregatedList o cualquier otro método que devuelva una lista), pagina los resultados siempre que sea posible para asegurarte de que lees toda la respuesta. Si no paginas, solo podrás recibir 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 información y ejemplos específicos, consulta la documentación de referencia del método list que quieras usar, como instances.list.
También puedes usar las bibliotecas de cliente de Cloud para gestionar la paginación.
Usar filtros de listas del lado del cliente para evitar errores de cuota
Si usas filtros con los métodos *.list o *.aggregatedList, se te cobrará una cuota adicional si hay más de 10.000 recursos filtrados en las solicitudes.
Para obtener más información, consulta filtered_list_cost_overhead
en Cuotas de velocidad.
Si tu proyecto supera esta cuota de frecuencia, recibirás un error 403 con el motivo rateLimitExceeded. Para evitar este error, usa filtros del lado del cliente en las solicitudes de lista.
Usar códigos de error, no mensajes de error
Las APIs de Google deben usar los códigos de error canónicos definidos por google.rpc.Code, pero los mensajes de error pueden cambiar sin previo aviso. Los mensajes de error suelen estar dirigidos a los desarrolladores, no a los programas.
Más información sobre los errores de la API
Minimizar los reintentos del lado del cliente para conservar las cuotas de frecuencia
Minimiza el número de reintentos del lado del cliente de un proyecto para evitar errores rateLimitExceeded y maximizar el uso de tus cuotas de frecuencia. Las siguientes prácticas pueden ayudarte a mantener las cuotas de frecuencia de tus proyectos:
- Evita las comprobaciones cortas.
- Usa las ráfagas con moderación y de forma selectiva.
- Haz siempre tus llamadas en un bucle de reintentos con un tiempo de espera exponencial.
- Usa un limitador de frecuencia del lado del cliente.
- Divide tus aplicaciones en varios proyectos.
Evitar el sondeo corto
Evita el sondeo corto, en el que tus clientes envían solicitudes continuamente al servidor sin esperar una respuesta. Si haces un sondeo breve, será más difícil detectar solicitudes incorrectas que se contabilicen en tu cuota, aunque no devuelvan datos útiles.
En lugar de usar el sondeo corto, debes esperar a que se completen las operaciones.
Usa la función de ráfaga con moderación y de forma selectiva
Usa las ráfagas con moderación y de forma selectiva. El bursting es la acción de permitir que un cliente específico haga muchas solicitudes a la API en poco tiempo. Por lo general, el bursting se realiza en respuesta a situaciones excepcionales, como cuando tu aplicación necesita gestionar más tráfico de lo habitual. El uso de ráfagas agota rápidamente tu cuota de velocidad, así que asegúrate de usarlo solo cuando sea necesario.
Cuando sea necesario hacer ráfagas, usa APIs por lotes específicas siempre que sea posible, como la API de instancias en bloque o los grupos de instancias gestionados.
Más información sobre las solicitudes por lotes
Siempre debes hacer las llamadas en un bucle de reintentos con un tiempo de espera exponencial
Usa un tiempo de espera exponencial para distribuir de forma progresiva las solicitudes cuando se agote el tiempo de espera o cuando alcances tu cuota de frecuencia.
Cualquier bucle de reintentos debe tener un retroceso exponencial que asegure que los reintentos frecuentes no sobrecarguen tu aplicación ni superen tus cuotas de frecuencia. De lo contrario, corres el riesgo de que se vean afectados negativamente todos los demás sistemas del mismo proyecto.
Si necesitas un bucle de reintentos para una operación que ha fallado porque has alcanzado la cuota de frecuencia, tu estrategia de retroceso exponencial debe permitir que transcurra el tiempo suficiente entre reintentos para que se vuelva a llenar el contenedor de cuota (normalmente, cada minuto).
Por otro lado, si necesitas un bucle de reintentos para cuando esperar una operación alcance el tiempo de espera, el intervalo máximo de tu estrategia de espera exponencial no debe superar el periodo de retención mínimo de la operación. De lo contrario, es posible que recibas un error Not Found de la operación.
Para ver un ejemplo de cómo implementar un tiempo de espera exponencial, consulta el algoritmo de tiempo de espera exponencial de la API Identity and Access Management.
Usar un limitador de frecuencia del lado del cliente
Usa un limitador de frecuencia del lado del cliente. Un limitador de frecuencia de cliente establece un límite artificial para que el cliente en cuestión solo pueda usar una cantidad determinada de cuota, lo que impide que un cliente consuma toda tu cuota.
Dividir las aplicaciones en varios proyectos
Dividir las aplicaciones en varios proyectos puede ayudar a minimizar el número de solicitudes de tus segmentos de cuota. Como las cuotas se aplican a nivel de proyecto, puedes dividir tus aplicaciones para que cada una tenga su propio contenedor de cuota.
Resumen de la lista de comprobación
En la siguiente lista de comprobación se resumen las prácticas recomendadas para usar la API de Compute Engine.
- Usar bibliotecas de cliente
- Generar solicitudes REST con la consola de Cloud
- Espera a que se completen las operaciones
- Paginación de los resultados de la lista
- Usa los códigos de error, no los mensajes de error
- Minimiza los reintentos del lado del cliente para conservar las cuotas de frecuencia de la API
Siguientes pasos
- Consulta cómo mejorar el rendimiento al usar la API de Compute Engine.