Este documento descreve as práticas recomendadas para usar a API Compute Engine e é destinado a usuários que já estão familiarizados com ela. Se você é iniciante, aprenda sobre os pré-requisitos e como usar a API Compute Engine .
Seguir essas práticas recomendadas pode ajudar você a economizar tempo, evitar erros e mitigar os efeitos das cotas tarifárias .
Use bibliotecas de cliente
As bibliotecas de cliente são a forma recomendada de acessar programaticamente a API Compute Engine. As bibliotecas cliente fornecem código que permite acessar a API por meio de linguagens de programação comuns, o que pode economizar tempo e melhorar o desempenho do seu código.
Saiba mais sobre as bibliotecas de cliente do Compute Engine e as práticas recomendadas para bibliotecas de cliente .
Gerar solicitações REST usando o Console do Cloud
Ao criar um recurso, gere a solicitação REST usando as páginas de criação de recursos ou páginas de detalhes no console do Google Cloud. Usar uma solicitação REST gerada economiza tempo e ajuda a evitar erros de sintaxe.
Aprenda como gerar solicitações REST .
Aguarde a conclusão das operações
Não presuma 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 verificar 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 GET HTTP, porque a resposta da API já indica se a solicitação foi bem-sucedida. 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 200 indique que o servidor recebeu sua solicitação de API com êxito, esse código de status não indica se a operação solicitada foi concluída com êxito ou não. Por exemplo, você pode receber um 200 , mas a operação pode ainda não ter sido concluída ou pode 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 é concluída 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 zonais, use
zoneOperations.wait. - Para operações regionais, use
regionOperations.wait. - Para operações globais, use
globalOperations.wait.
O método wait retorna quando a operação é concluída ou quando a solicitação está se aproximando do prazo de 2 minutos. Ao usar o método wait , evite polling curto, que ocorre quando seus clientes fazem solicitações continuamente ao servidor sem esperar por uma resposta. Usar o método wait em um loop de nova tentativa com espera exponencial para verificar o status da sua solicitação, em vez de usar o método get com sondagem curta para o recurso Operation , ajuda a preservar suas cotas de taxa e reduz a latência.
Para obter mais informações e exemplos de uso do método wait , consulte Tratamento de respostas da API .
Para verificar o status de uma operação solicitada, consulte Verificando o status da operação .
Enquanto aguarda a conclusão de uma operação, considere o período mínimo de retenção da operação , pois as operações concluídas podem ser removidas do banco de dados após esse período.
Paginar resultados da lista
Ao usar um método de lista (como um método *.list , um método *.aggregatedList ou qualquer outro método que retorne uma lista), paginar os resultados sempre que possível para garantir que você leia a resposta inteira. Se você não paginar, poderá receber apenas até os primeiros 500 elementos, conforme determinado pelo parâmetro de consulta maxResults .
Para obter mais informações sobre paginação no Google Cloud, consulte Paginação de lista . Para obter detalhes e exemplos específicos, consulte a documentação de referência do método list que você deseja usar, como instances.list .
Você também pode usar bibliotecas de cliente em nuvem para lidar com a paginação .
Use filtros de lista do lado do cliente para evitar erros de cota
Ao usar filtros com métodos *.list ou *.aggregatedList , você incorrerá em cobranças de cota adicionais se houver mais de 10 mil recursos filtrados das solicitações. Para obter mais informações, consulte filtered_list_cost_overhead em Cotas de taxa.
Se o seu 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 de lista.
Confie em códigos de erro, não em mensagens de erro
As APIs do Google devem 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. As mensagens de erro geralmente são destinadas à leitura dos desenvolvedores, não aos programas.
Saiba mais sobre erros de API .
Minimize as novas tentativas do lado do cliente para preservar as cotas tarifárias
Minimize o número de novas tentativas do lado do cliente para um projeto para evitar erros rateLimitExceeded e maximizar a utilização de suas cotas de taxas . As práticas a seguir podem ajudá-lo a preservar as cotas tarifárias para seus projetos:
- Evite pesquisas curtas.
- Use o bursting com moderação e seleção.
- Sempre faça suas chamadas em um loop de novas tentativas com espera exponencial.
- Use um limitador de taxa do lado do cliente.
- Divida seus aplicativos em vários projetos.
Evite pesquisas curtas
Evite pesquisas curtas, nas quais seus clientes fazem solicitações contínuas ao servidor sem esperar por uma resposta. Se você fizer uma pesquisa curta, será mais difícil capturar solicitações incorretas que contam em sua cota, mesmo que elas não retornem dados úteis.
Em vez de uma pesquisa curta, você deve aguardar a conclusão das operações .
Use o bursting com moderação e seleção
Use o bursting com moderação e seleção. Bursting é o ato de permitir que um cliente específico faça muitas solicitações de API em um curto espaço de tempo. Normalmente, o bursting é feito em resposta a cenários excepcionais, como casos em que seu aplicativo precisa lidar com mais tráfego do que o normal. O estouro de sua cota tarifária rapidamente, portanto, certifique-se de usá-lo somente quando necessário.
Quando o bursting for necessário, use APIs em lote dedicadas sempre que possível, como a API de instância em massa ou grupos de instâncias gerenciadas .
Saiba mais sobre solicitações em lote .
Sempre faça suas chamadas em um loop de novas tentativas com espera exponencial
Use a espera exponencial para espaçar progressivamente as solicitações quando elas atingirem o tempo limite ou sempre que você atingir sua cota de taxa.
Qualquer loop de repetição deve ter uma espera exponencial que garanta que tentativas frequentes não sobrecarreguem seu aplicativo nem excedam suas cotas de taxa. Caso contrário, você corre o risco de impactar 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 deverá permitir tempo suficiente entre as tentativas para que o intervalo de cota seja recarregado (geralmente a cada minuto).
Como alternativa, se você precisar de um loop de repetição para quando a espera de uma operação atingir o tempo limite, o intervalo máximo da sua estratégia de espera exponencial não deverá exceder o período mínimo de retenção da operação. Caso contrário, você poderá receber um erro de operação Not Found .
Para obter um exemplo de implementação de espera exponencial, consulte o algoritmo de espera exponencial para a API de gerenciamento de identidade e acesso.
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 possa usar apenas uma determinada quantidade de cota, o que evita que qualquer cliente consuma toda a sua cota.
Divida seus aplicativos em vários projetos
Dividir seus aplicativos em vários projetos pode ajudar a minimizar o número de solicitações para seus intervalos de cota. Como as cotas são aplicadas por projeto, você pode dividir seus aplicativos para que cada aplicativo tenha seu próprio intervalo de cotas dedicado.
Resumo da lista de verificação
A lista de verificação a seguir resume as práticas recomendadas para usar a API Compute Engine.
- Use bibliotecas de cliente
- Gerar solicitações REST usando o Console do Cloud
- Aguarde a conclusão das operações
- Paginar resultados da lista
- Confie em códigos de erro, não em mensagens de erro
- Minimize as novas tentativas do lado do cliente para preservar as cotas de taxas de API
O que vem a seguir
- Saiba como melhorar o desempenho ao usar a API Compute Engine .