Neste documento, descrevemos as práticas recomendadas para o uso da API Compute Engine e se destina a usuários que já estão familiarizados com ela. Se você é um iniciante, conheça os pré-requisitos e como usar a API Compute Engine.
Seguir essas práticas recomendadas pode ajudar você a economizar tempo, evitar erros e reduzir os efeitos das cotas de taxa.
Usar as bibliotecas de cliente
As bibliotecas de cliente são a maneira recomendada de acessar programaticamente a API Compute Engine. As bibliotecas de cliente fornecem código que permite acessar a API por meio de linguagens de programação comuns, o que economiza tempo e melhora o desempenho do código.
Saiba mais sobre as bibliotecas de cliente do Compute Engine e as práticas recomendadas da biblioteca de cliente.
Gerar solicitações REST usando o Console do Cloud
Ao criar um recurso, gere a solicitação REST nas páginas de criação de recursos ou nas páginas de detalhes no console do Google Cloud. O uso de uma solicitação REST gerada economiza tempo e ajuda a evitar erros de sintaxe.
Saiba como gerar solicitações REST.
Aguardar operações serem concluídas
Não suponha que uma operação (qualquer solicitação de API que altere um recurso) foi concluída ou bem-sucedida. Em vez disso, use um método wait para o recurso Operation e verifique se a operação foi concluída. Você não precisa verificar uma solicitação que não modifica recursos, como uma solicitação de leitura usando um verbo HTTP GET, porque a resposta da API já indica se a solicitação foi bem-sucedido. Consequentemente, a API Compute Engine não retorna recursos Operation para essas solicitações.
Sempre que uma solicitação de API é iniciada com sucesso, ela retorna um código de status HTTP 200. Embora o recebimento de um 200 indique que o servidor recebeu sua solicitação de API com sucesso, esse código de status não indica se a operação solicitada foi concluída com sucesso. Por exemplo,
é possível receber um 200, mas a operação pode não ter sido concluída ainda
ou ter falhado.
Qualquer solicitação para criar, atualizar ou excluir uma
operação de longa duração
retorna um
recurso Operation,
que captura o status dessa solicitação. Uma operação é feita quando o
campo status do recurso Operation é DONE. Para verificar o status, use o método wait que corresponde ao escopo do recurso Operation retornado:
- Para operações por zona, use
zoneOperations.wait. - Para operações regionais, use
regionOperations.wait. - Para operações globais, use
globalOperations.wait.
O método wait é retornado quando a operação é concluída ou quando a solicitação está
se aproximando do prazo de dois minutos. Ao usar o método wait, evite pesquisas curtas, que são quando seus clientes fazem solicitações continuamente ao servidor sem aguardar uma resposta. Usar o método wait em um loop de
tentativas com espera exponencial para verificar o
status da solicitação, em vez de usar o método get com pesquisa curta
para o recurso Operation, ajuda a preservar suas cotas de taxa e reduz a latência.
Para mais informações sobre exemplos do uso do método wait, consulte
Como processar respostas de API.
Para verificar o status de uma operação solicitada, consulte Como verificar o status da operação.
Enquanto aguarda a conclusão de uma operação, considere o período de armazenamento mínimo da operação, já que as operações concluídas podem ser removidas do banco de dados após esse período.
Resultados de lista de paginação
Ao usar um método de lista (como *.list, *.aggregatedList ou qualquer outro que retorne uma lista), paginar sempre que possível para garantir que
você leia toda a resposta. Se você não realizar a paginação, só poderá receber até
os primeiros 500 elementos, conforme determinado pelo
parâmetro de consulta maxResults.
Para mais informações sobre paginação no Google Cloud, consulte Listar paginação.
Para detalhes e exemplos específicos, consulte a documentação de referência do
método de lista que você quer usar, como
instances.list.
Também é possível usar as bibliotecas de cliente do Cloud para processar a paginação.
Usar filtros de lista do lado do cliente para evitar erros de cota
Ao usar filtros com os métodos *.list ou *.aggregatedList, haverá
cobranças de cota adicionais se houver mais de 10 mil recursos filtrados nas
solicitações.
Para mais informações, consulte filtered_list_cost_overhead
em cotas de taxa.
Se o projeto exceder essa cota de taxa, você receberá um erro 403 com o motivo rateLimitExceeded. Para evitar esse erro,
use filtros do lado do cliente para as solicitações da lista.
Conte com códigos de erro, não mensagens de erro
As APIs do Google precisam usar os códigos de erro canônicos definidos por
google.rpc.Code,
mas as mensagens de erro
podem estar sujeitas a alterações sem aviso prévio. Geralmente, as mensagens de erro são destinadas
a desenvolvedores, e não a programas.
Saiba mais sobre os erros de API.
Minimizar as tentativas do lado do cliente para preservar as cotas de taxa
Minimize o número de novas tentativas do lado do cliente em um projeto para evitar erros rateLimitExceeded e maximizar a utilização das cotas de taxa. As práticas a seguir
podem ajudar a preservar as cotas de taxa dos seus projetos:
- Evite pesquisas curtas.
- Use o bursting de forma moderada e seletiva.
- Sempre faça chamadas em um loop de repetição com espera exponencial.
- Use uma limitação de taxa no lado do cliente.
- Divida seus aplicativos em vários projetos.
Evite pesquisas curtas
Evite pesquisas curtas, em que seus clientes continuamente fazem solicitações ao servidor sem esperar por uma resposta. Se você fizer uma pesquisa curta, será mais difícil detectar solicitações incorretas que sejam contadas na sua cota, mesmo que elas não retornem dados úteis.
Em vez de pesquisas curtas, você deve aguardar a conclusão de operações.
Use o bursting com moderação e seletivamente
Use o bursting de forma moderada e seletiva. Bursting é o ato de permitir que um cliente específico faça muitas solicitações de API em um curto período de tempo. Geralmente, isso é feito em resposta a cenários excepcionais, como casos em que seu aplicativo precisa lidar com mais tráfego do que o normal. O bursting queima as cotas de taxa rapidamente, portanto, use-o apenas quando for necessário.
Quando o bursting for necessário, use APIs em lote dedicadas quando possível, como a API de instância em massa ou os grupos de instâncias gerenciadas.
Saiba mais sobre solicitações em lote.
Sempre faça chamadas em um loop de repetição com espera exponencial
Use a espera exponencial para distribuir progressivamente as solicitações quando elas atingirem o tempo limite ou sempre que você atingir a cota de taxa.
Todo loop de repetição precisa ter uma espera exponencial para garantir que novas tentativas frequentes não sobrecarreguem o aplicativo nem excedam as cotas de taxa. Caso contrário, você corre o risco de afetar negativamente todos os outros sistemas no mesmo projeto.
Se você precisar de um loop de repetição para uma operação que falhou porque atingiu a cota de taxa, sua estratégia de espera exponencial permitirá tempo suficiente entre novas tentativas para que o bucket de cota seja recarregado (geralmente a cada minuto).
Como alternativa, se você precisar de um loop de tentativas enquanto a aguardar uma operação
atingir o tempo limite, o intervalo máximo da estratégia de espera exponencial
não poderá exceder o período de armazenamento mínimo da operação. Caso contrário, você pode
receber um erro Not Found de operação.
Para conferir um exemplo de como implementar a espera exponencial, consulte o algoritmo de espera exponencial da API Identity and Access Management.
Use uma limitação de taxa no lado do cliente
Use uma limitação de taxa no lado do cliente. Um limitador de taxa do lado do cliente define um limite artificial para que o cliente em questão use apenas uma determinada quantidade de cota, o que impede que um cliente consuma toda sua cota.
Divida seus aplicativos em vários projetos
A divisão dos aplicativos em vários projetos pode ajudar a minimizar o número de solicitações para os buckets de cota. Como as cotas são aplicadas em um nível por projeto, é possível dividir seus aplicativos para que cada aplicativo tenha um bucket de cotas próprio dedicado.
Lista de verificação resumida
A lista de verificação a seguir resume as práticas recomendadas para usar a API Compute Engine.
- Usar as bibliotecas de cliente
- Gerar solicitações REST usando o Console do Cloud
- Aguardar operações
- Paginar os resultados da lista
- Usar códigos de erro, não mensagens de erro
- Minimize novas tentativas do lado do cliente para preservar as cotas de taxa de API