Este documento descreve as práticas recomendadas para usar a API Compute Engine e destina-se a utilizadores que já a conhecem. Se for principiante, saiba mais sobre os pré-requisitos e a utilização da API Compute Engine.
Seguir estas práticas recomendadas pode ajudar a poupar tempo, evitar erros e mitigar os efeitos das quotas de taxa.
Use bibliotecas de cliente
As bibliotecas cliente são a forma recomendada de aceder programaticamente à API Compute Engine. As bibliotecas cliente fornecem código que lhe permite aceder à API através de linguagens de programação comuns, o que pode poupar-lhe tempo e melhorar o desempenho do seu código.
Saiba mais sobre as bibliotecas cliente do Compute Engine e as práticas recomendadas para bibliotecas cliente.
Gere pedidos REST através da Cloud Console
Quando criar um recurso, gere o pedido REST através das páginas de criação de recursos ou das páginas de detalhes na Trusted Cloud consola. A utilização de um pedido REST gerado poupa tempo e ajuda a evitar erros de sintaxe.
Saiba como gerar pedidos REST.
Aguarde a conclusão das operações
Não assuma que uma operação, ou seja, qualquer pedido de API que altere um recurso, está concluída ou foi bem-sucedida. Em alternativa, use um método wait para o recurso Operation para validar que a operação foi concluída. (Não precisa de validar um pedido que não modifique recursos, como um pedido de leitura, usando um verbo HTTP GET, porque a resposta da API já indica se o pedido foi bem-sucedido. Consequentemente, a API Compute Engine não devolve recursos Operation para estes pedidos.)
Sempre que um pedido de API é iniciado com êxito, devolve um código de estado HTTP
200. Embora a receção de um 200 indique que o servidor recebeu o seu pedido de API com êxito, este código de estado não indica se a operação pedida foi concluída com êxito ou não. Por exemplo, pode receber um 200, mas a operação ainda pode não estar concluída ou pode ter falhado.
Qualquer pedido de criação, atualização ou eliminação de uma
operação de longa duração
devolve um
recursoOperation,
que capta o estado desse pedido. Uma operação é concluída quando o campo status do recurso Operation é DONE. Para verificar o estado,
use o método wait que corresponde ao
âmbito
do recurso Operation devolvido:
- Para operações zonais, use
zoneOperations.wait. - Para operações regionais, use
regionOperations.wait. - Para operações globais, use
globalOperations.wait.
O método wait é devolvido quando a operação é concluída ou quando o pedido se aproxima do prazo de 2 minutos. Quando usar o método wait, evite a sondagem curta, que ocorre quando os seus clientes fazem pedidos continuamente ao servidor sem esperar por uma resposta. A utilização do método wait num ciclo de repetição com rejeição exponencial para verificar o estado do seu pedido, em vez de usar o método get com sondagem curta para o recurso Operation, ajuda a preservar as suas quotas de taxa e reduz a latência.
Para mais informações e exemplos de utilização do método wait, consulte o artigo
Processar respostas da API.
Para verificar o estado de uma operação pedida, consulte o artigo Verificar o estado da operação.
Enquanto aguarda pela conclusão de uma operação, tenha em conta o período de retenção mínimo da operação, uma vez que as operações concluídas podem ser removidas da base de dados após este período.
Pagine os resultados da lista
Quando usar um método de lista (como um método *.list, um método *.aggregatedList ou qualquer outro método que devolva uma lista), pagine os resultados sempre que possível para garantir que lê a resposta completa. Se não fizer a paginação, só pode receber até aos primeiros 500 elementos, conforme determinado pelo parâmetro de consulta maxResults.
Para mais informações sobre a paginação no Google Cloud, consulte o artigo
Paginação de listas.
Para ver detalhes e exemplos específicos, consulte a documentação de referência do método de lista que quer usar, como instances.list.
Também pode usar as bibliotecas cliente da Google Cloud para processar a paginação.
Use filtros de listas do lado do cliente para evitar erros de quota
Quando usa filtros com os métodos *.list ou *.aggregatedList, incorre em custos de quota adicionais se existirem mais de 10 mil recursos filtrados a partir dos pedidos.
Para mais informações, consulte filtered_list_cost_overhead
em Quotas de taxa.
Se o seu projeto exceder esta quota de taxa, recebe um erro 403 com o motivo rateLimitExceeded. Para evitar este erro,
use filtros do lado do cliente para os pedidos de listas.
Confie nos códigos de erro e não nas mensagens de erro
As APIs Google têm de usar os códigos de erro canónicos definidos por
google.rpc.Code,
mas as mensagens de erro
podem ser alteradas sem aviso prévio. Geralmente, as mensagens de erro destinam-se
a ser lidas por programadores e não por programas.
Saiba mais sobre os erros da API.
Minimize as novas tentativas do lado do cliente para preservar as quotas de taxa
Minimize o número de novas tentativas do lado do cliente para um projeto para evitar erros rateLimitExceeded e maximizar a utilização das suas quotas de taxa. As seguintes práticas
podem ajudar a preservar as quotas de taxa dos seus projetos:
- Evite a sondagem curta.
- Use as rajadas com moderação e de forma seletiva.
- Faça sempre as suas chamadas num loop de repetição com retirada exponencial.
- Use um limitador de taxa do lado do cliente.
- Divida as suas aplicações por vários projetos.
Evite a sondagem curta
Evite a sondagem curta, em que os seus clientes fazem pedidos continuamente ao servidor sem esperar por uma resposta. Se fizer pedidos curtos, é mais difícil detetar pedidos inválidos que contam para a sua quota, mesmo que não devolvam dados úteis.
Em vez de sondagens curtas, deve aguardar que as operações sejam concluídas.
Use as rajadas com moderação e de forma seletiva
Use as rajadas com moderação e de forma seletiva. O envio rápido é o ato de permitir que um cliente específico faça muitos pedidos de API num curto período. Normalmente, o aumento é feito em resposta a cenários excecionais, como casos em que a sua aplicação tem de processar mais tráfego do que o habitual. O envio em massa esgota rapidamente a sua quota de taxa, por isso, certifique-se de que a usa apenas quando necessário.
Quando for necessário o aumento repentino, use APIs de lote dedicadas sempre que possível, como a API de instâncias em massa ou os grupos de instâncias geridos.
Saiba mais acerca dos pedidos em lote.
Faça sempre as suas chamadas num loop de repetição com retirada exponencial
Use a retirada exponencial para espaçar progressivamente os pedidos quando atingirem o limite de tempo ou sempre que atingir a sua quota de taxa.
Qualquer ciclo de repetição deve ter uma retirada exponencial que garanta que as repetições frequentes não sobrecarregam a sua aplicação nem excedem as quotas de taxas. Caso contrário, corre o risco de afetar negativamente todos os outros sistemas no mesmo projeto.
Se precisar de um ciclo de repetição para uma operação que falhou porque atingiu a quota de taxa, a sua estratégia de recuo exponencial deve permitir tempo suficiente entre as repetições para que o intervalo da quota seja reposto (normalmente, a cada minuto).
Em alternativa, se precisar de um ciclo de repetição quando aguardar uma operação atingir o limite de tempo, o intervalo máximo da sua estratégia de recuo exponencial não deve exceder o período de retenção mínimo da operação. Caso contrário, pode receber um erro de operação Not Found.
Para ver um exemplo de implementação da retirada exponencial, consulte o algoritmo de retirada exponencial para a API Identity and Access Management.
Use um limitador de taxa do lado do cliente
Use um limitador de taxa do lado do cliente. Um limitador de taxa do lado do cliente define um limite artificial para que o cliente em questão só possa usar uma determinada quantidade de quota, o que impede que um cliente consuma toda a sua quota.
Divida as suas aplicações em vários projetos
Dividir as suas aplicações em vários projetos pode ajudar a minimizar o número de pedidos para os seus limites de quota. Uma vez que as quotas são aplicadas ao nível do projeto, pode dividir as suas aplicações para que cada aplicação tenha o seu próprio conjunto de quotas dedicado.
Resumo da lista de verificação
A seguinte lista de verificação resume as práticas recomendadas para usar a API Compute Engine.
- Use bibliotecas cliente
- Gere pedidos REST através da Cloud Console
- Aguarde a conclusão das operações
- Paginar resultados da lista
- Confie nos códigos de erro e não nas mensagens de erro
- Minimize as repetições do lado do cliente para preservar as quotas de taxa da API