Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como gerenciar uma cota de serviço

Nesta página, descrevemos como visualizar todas as métricas e limites em um projeto do Google Cloud para um serviço específico e como limitar o uso da cota para esse serviço usando uma substituição de cota. É possível usar o Service Usage para gerenciar a cota dos seus projetos para qualquer serviço, incluindo serviços públicos do Google Cloud e serviços privados criados com o Cloud Endpoints. Para mais informações sobre as diferenças entre APIs e serviços públicos e privados, consulte Serviços públicos e privados.

Na maioria dos casos de uso operacional, a maneira mais simples de gerenciar cotas é usar o Console do Google Cloud. Se precisar programar com a API Service Usage, recomendamos que você use uma das bibliotecas de clientes fornecidas. Para testar a API, siga as instruções deste guia e use o comando gcurl para testar a API sem configurar um ambiente de desenvolvimento completo de aplicativos.

Antes de começar

Para usar os exemplos desta página, conclua todas as etapas listadas no guia de Primeiros passos. Essas etapas incluem definir gcurl, que é um alias autenticado para o comando curl padrão e definir a variável de ambiente PROJECT_NUMBER.

Certifique-se de se familiarizar com o modelo de cota de serviço para entender melhor a terminologia usada neste tutorial.

Como exibir a cota de serviço

Para ver todas as métricas e limites de cotas que se aplicam a um consumidor específico em um serviço, use o seguinte comando:

gcurl "https://serviceusage.googleapis.com/v1beta1/projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics"

A chamada responde com uma lista de métricas definidas pelo serviço, cada uma com a lista de limites que se aplicam a esse consumidor, os valores desses limites e as modificações. Veja um exemplo de resposta parcial:


{
  "metrics": [
    ...
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus",
      "displayName": "CPUs",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fzone",
          "unit": "1/{project}/{zone}",
          "isPrecise": true,
          "metric": "compute.googleapis.com/cpus",
          "quotaBuckets": [
            {
              "effectiveLimit": "-1",
              "defaultLimit": "-1"
            }
          ]
        },
        {
          "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fregion",
          "unit": "1/{project}/{region}",
          "isPrecise": true,
          "metric": "compute.googleapis.com/cpus",
          "quotaBuckets": [
            {
              "effectiveLimit": "24",
              "defaultLimit": "24"
            },
            {
              "effectiveLimit": "72",
              "defaultLimit": "72",
              "dimensions": {
                "region": "asia-northeast1"
              }
            },

            ...

            {
              "effectiveLimit": "72",
              "defaultLimit": "72",
              "dimensions": {
                "region": "australia-southeast1"
              }
            }
          ]
        }
      ],
      "metric": "compute.googleapis.com/cpus",
      "unit": "1"
    },
    ...
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways",
      "displayName": "External VPN gateways",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject",
          "unit": "1/{project}",
          "isPrecise": true,
          "metric": "compute.googleapis.com/external_vpn_gateways",
          "quotaBuckets": [
            {
              "effectiveLimit": "15",
              "defaultLimit": "15"
            }
          ]
        }
      ],
      "metric": "compute.googleapis.com/external_vpn_gateways",
      "unit": "1"
    },
    ...

Cada métrica na resposta tem um campo name. Para inspecionar as configurações de cota apenas para essa métrica, e não para todas as métricas, use name no URL. Neste tutorial, a variável de ambiente METRIC_RESOURCE_NAME armazena o nome do recurso de métrica da cota:

METRIC_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways"
gcurl "https://serviceusage.googleapis.com/v1beta1/${METRIC_RESOURCE_NAME}"

Como um nome de recurso de métrica específico é fornecido, a chamada retorna somente as informações dessa métrica:

{
  "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways",
  "displayName": "External VPN gateways",
  "consumerQuotaLimits": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject",
      "unit": "1/{project}",
      "isPrecise": true,
      "metric": "compute.googleapis.com/external_vpn_gateways",
      "quotaBuckets": [
        {
          "effectiveLimit": "15",
          "defaultLimit": "15"
        }
      ]
    }
  ],
  "metric": "compute.googleapis.com/external_vpn_gateways",
  "unit": "1"
}

Da mesma forma, cada limite dentro de uma métrica tem um campo name. Para inspecionar as configurações de cota apenas para o limite em questão nessa métrica, e não para todos os limites de uma métrica ou de todas as métricas, use o name no URL. Neste tutorial, a variável de ambiente LIMIT_RESOURCE_NAME armazena o nome do recurso de limite de cota:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}"

Quando um limite específico é fornecido, a chamada retorna apenas as informações desse limite:

{
  "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject",
  "unit": "1/{project}",
  "isPrecise": true,
  "metric": "compute.googleapis.com/external_vpn_gateways",
  "quotaBuckets": [
    {
      "effectiveLimit": "15",
      "defaultLimit": "15"
    }
  ]
}

Como criar uma substituição de cota do consumidor

O proprietário de um projeto pode aplicar uma modificação de consumidor a um limite de cota específico nesse projeto. Isso reduzir a quantidade total de cota que o consumidor pode cobrar em relação a esse limite.

Uma modificação do consumidor não pode aumentar a cota disponível além do permitido pelo padrão de serviço nem permite qualquer modificação atual feita por outras partes, como o proprietário do serviço ou o administrador de cotas de uma organização. Para aumentar a cota disponível, use a opção Editar cotas na página de cota principal ou solicite um aumento de cota ao administrador da organização.

Para identificar um limite para substituir, use primeiro um dos métodos anteriores para encontrar o limite de cota de interesse. Em seguida, use o campo de nome do limite de cota para criar uma nova modificação do consumidor nesse limite. O exemplo a seguir refere-se ao limite por projeto da métrica de cota "Gateways de VPN externos" do serviço do Compute Engine:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides" -d '{"overrideValue": "14"}'

Quando a chamada é bem-sucedida, ela retorna um identificador de operação, que representa o trabalho contínuo no servidor, à medida que a alteração de cota é propagada para sistemas de back-end:

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

Para verificar o progresso da operação, basta usar o name:

OPERATION_NAME="operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
gcurl "https://serviceusage.googleapis.com/v1/${OPERATION_NAME}"

Se a operação for bem-sucedida, a mensagem de resposta incluirá done: true e conterá o recurso de modificação recém-criado. Se a operação falhar, a mensagem de resposta incluirá done: true, mas conterá detalhes do erro em vez do recurso.

Para verificar se a modificação foi criada, liste todas as modificações do consumidor para o limite:

gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides"

A substituição recém-criada deve aparecer na lista:

{
  "overrides": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl",
      "overrideValue": "14"
    }
  ]
}

Como criar modificações de cota regionais ou sazonais

Alguns limites de cota são aplicados por região ou zona. Isso é indicado pela presença de {region} ou {zone} no campo unit do limite. Por exemplo, um limite com a unidade "1/{project}/{region}" é aplicado por região. A aplicação de uma modificação a esse limite altera a cota base em cada região ou zona. Para alterar a cota de uma região ou zona específica, adicione uma dimensão de cota usando o campo dimensions ao criar a modificação. Por exemplo, crie uma modificação regional em um limite de cota regional do Compute Engine assim:

REGIONAL_LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fregion"
gcurl "https://serviceusage.googleapis.com/v1beta1/${REGIONAL_LIMIT_RESOURCE_NAME}/consumerOverrides" -d '{"overrideValue": "65", "dimensions": {"region": "southamerica-east1"} }'

Para verificar se a modificação regional foi criada, liste todas as modificações do consumidor para o limite:

gcurl "https://serviceusage.googleapis.com/v1beta1/${REGIONAL_LIMIT_RESOURCE_NAME}/consumerOverrides"

A modificação regional recém-criada deve aparecer na lista:

{
  "overrides": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fcpus/limits/%2Fproject%2Fregion/consumerOverrides/Cg1RdW90YU92ZXJyaWRlGhwKBnJlZ2lvbhISc291dGhhbWVyaWNhLWVhc3Qx",
      "overrideValue": "65",
      "dimensions": {
        "region": "southamerica-east1"
      }
    }
  ]
}

Como atualizar uma modificação de cota do consumidor

O proprietário de um projeto também pode alterar o valor de uma modificação de consumidor existente no projeto.

Por exemplo, suponha que uma chamada de criação anterior retorne uma modificação com um campo name como este:

name: "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"

Em seguida, use esse nome para identificar a substituição a ser atualizada, desta maneira:

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"
gcurl "https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME}" -X PATCH -d '{"overrideValue": "13"}'

Quando a chamada é bem-sucedida, ela retorna um identificador de operação, que representa o trabalho contínuo no servidor, à medida que a alteração de cota é propagada para sistemas de back-end:

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

Para verificar o progresso da operação, basta usar o name:

OPERATION_NAME="operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
gcurl "https://serviceusage.googleapis.com/v1/${OPERATION_NAME}"

Se a operação for bem-sucedida, a mensagem de resposta incluirá done: true e conterá o recurso de modificação atualizado. Se a operação falhar, a mensagem de resposta incluirá done: true, mas conterá detalhes do erro em vez do recurso atualizado.

Para verificar se a modificação foi atualizada, liste todas as modificações do consumidor para o limite:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides"

A modificação aparecerá na lista com o valor atualizado:

{
  "overrides": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl",
      "overrideValue": "13"
    }
  ]
}

Como excluir uma modificação de cota do consumidor

O proprietário de um projeto também pode remover uma modificação de consumidor do projeto.

Por exemplo, suponha que uma chamada de criação anterior retorne uma modificação com um campo name como este:

name: "projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"

Para excluir a modificação, emita a seguinte sequência:

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/Cg1RdW90YU92ZXJyaWRl"
gcurl "https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME}" -X DELETE

Para verificar se a modificação foi excluída, liste todas as modificações do consumidor para o limite:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides"

A modificação excluída não aparecerá mais na lista.

Como forçar grandes alterações de cota

Se qualquer modificação de substituição de cota fizer com que a cota aplicada diminua em mais de 10%, a chamada será rejeitada, como uma medida de segurança para evitar a redução acidental da cota muito rapidamente. Para desconsiderar essa restrição, use a sinalização force. Por exemplo, esta é uma chamada de criação que recebe o sinalização forçada:

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/compute.googleapis.com/consumerQuotaMetrics/compute.googleapis.com%2Fexternal_vpn_gateways/limits/%2Fproject"
gcurl "https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides?force=true" -d '{"overrideValue": "0"}'