Cotas

Este documento lista as cotas que se aplicam à API Merchant.

A API Merchant usa cotas para ajudar a garantir um ambiente estável e justo para todos os usuários. As cotas impedem que um único usuário da API coloque uma carga excessiva no sistema, garantindo alto desempenho. Entender essas cotas é fundamental para gerenciar os dados de produtos e dimensionar sua empresa no Google.

Conceitos gerais

As cotas da API Merchant são gerenciadas por grupos de cotas.

Os métodos de API são mapeados para grupos de cotas. A estrutura desse mapeamento pode variar:

  • Método único por grupo:alguns grupos de cotas se aplicam a um único método de API. Por exemplo, o método de fontes de dados de informações do produto accounts.dataSources.list tem um grupo de cotas dedicado.
  • Vários métodos por grupo (agrupamento) : geralmente, os métodos relacionados são agrupados em um único grupo de cotas. Todos os métodos desse grupo compartilham os mesmos limites diários e por minuto. Exemplos comuns incluem:
    • Agrupar todas as operações de leitura para métodos e recursos relacionados, como merchant-accounts-read-methods.
    • Agrupar todas as operações de gravação para métodos e recursos relacionados, como merchant-accounts-write-methods.

Cada chamada de método é contabilizada uma vez, independentemente do tipo. Uma solicitação list de 250 itens é contabilizada apenas uma vez, não como 250 solicitações get.

O lote HTTP integrado não influencia a cota. Cada solicitação única em um lote de solicitações é contabilizada como uma na cota. Por exemplo, uma solicitação em lote que contém 500 solicitações insert é cobrada como 500 solicitações de método insert individuais.

Exceção para lote de região dedicada: os métodos de lote de região especializados (batchCreate, batchUpdate, batchDelete) são contabilizados como uma única chamada de API no grupo de cotas merchant_regions, independentemente do número de operações de região contidas no payload.

Para gerenciar sua integração de maneira eficaz, revise o grupo de cotas específico associado a cada método de API que você pretende usar. Você pode encontrar esses detalhes no método de lista de cotas. Para mais informações, consulte Monitoramento e visibilidade.

Atualizar política

A API Merchant aplica as seguintes políticas em termos de atualizações:

  • Por padrão, você pode atualizar seus produtos até duas vezes por dia. Espalhe as chamadas uniformemente ao longo do dia para obedecer à cota por minuto.
  • Por padrão, você só pode atualizar suas subcontas até duas vezes por dia. Sua cota diária de atualização de subcontas é um limite agregado com base no total de subcontas permitidas.
  • Por padrão, você só pode chamar métodos de fonte de dados para suas subcontas, como list ou create, até duas vezes por subconta por dia.

cotas de taxa.

Cada grupo de cotas tem dois tipos de limites (e uso diário):

  • Limite diário (quotaLimit) : o número máximo de solicitações permitidas por dia. Os limites de cota diária são redefinidos às 12h UTC.
  • Limite por minuto (quotaMinuteLimit) : o número máximo de solicitações permitidas por minuto, controlando a taxa de solicitações. Os limites de cota por minuto usam uma janela móvel, em que o período de aplicação começa no momento em que a primeira chamada de API para esse método e recurso é feita. Por exemplo, se você fizer uma chamada às 10h01min30, a janela de cota por minuto para esse método será executada até as 10h02min30.
  • Uso diário (quotaUsage) : o número de solicitações que já foram feitas e contabilizadas no limite diário do dia atual. Se o campo estiver ausente, nenhuma cota foi consumida para esse grupo ainda.

Você pode encontrar os três campos descritos anteriormente (quotaLimit, quotaMinuteLimit, e quotaUsage) na resposta do quotas.list método.

Os limites diários e por minuto específicos variam significativamente entre diferentes grupos de cotas. Operações com maior volume esperado ou menor custo do sistema, como a leitura de dados de produtos, geralmente têm limites mais altos. Por outro lado, operações mais intensivas ou sensíveis, como modificações de contas, podem ter limites mais baixos.

Alocação e hierarquia de cotas

Esta seção explica em nome de quem a API Merchant rastreia e aplica o uso de cotas:

Em geral, a cota é cobrada com base no usuário que faz a solicitação de API.

  • Contas independentes:para contas independentes que autenticam uma chamada de API, essa solicitação é contabilizada na cota da conta.
    • Exemplo: um comerciante Loja de sapatos A (ID da conta: 12345) faz a autenticação usando a própria conta de serviço para chamar products.insert direcionando para a própria conta (accounts/12345). A cota é consumida do pool de cotas da Loja de sapatos A's.
  • Contas avançadas: a autenticação como uma conta avançada consome a cota do pool da conta avançada, mesmo ao segmentar uma subconta.
    • Exemplo:uma agência Conta de gerenciamento de varejo (ID da conta avançada: 12345) gerencia uma subconta Loja de roupas B (ID da conta: 11111). A agência faz a autenticação usando as próprias credenciais e chama products.insert direcionando para a Loja de roupas B (accounts/11111). A cota é consumida do pool da agência mãe (ID da conta avançada: 12345), não do pool da subconta.
  • Subcontas:quando as chamadas de API são autenticadas usando as credenciais de uma subconta, a cota é cobrada no pool individual dessa subconta. Isso funciona da mesma forma que uma conta independente, mesmo que seja gerenciada por uma conta avançada mãe.
    • Exemplo: usando a mesma configuração anterior, se a Loja de roupas B (ID da conta: 11111) fizer a autenticação usando credenciais configuradas especificamente para a subconta para chamar products.insert direcionando para a própria conta (accounts/11111), a cota será consumida do pool de cotas individual da Loja de roupas B, deixando o pool da agência mãe intacto.

Exceções às regras gerais

Há algumas exceções específicas que se aplicam às regras gerais de alocação de cotas:

  • Accounts.list: A cota para este método é cobrada do usuário autenticado ou da conta de serviço que faz a chamada, não do ID da conta do Merchant Center. O uso da cota não fica visível na página de diagnóstico padrão da API Merchant Center . Se você tiver uma conta avançada, recomendamos usar o accounts.listSubaccounts método, que é contabilizado na cota das contas avançadas.
  • Métodos de resolução de problemas: esses métodos sempre são contabilizados na cota da conta cujos problemas estão sendo solicitados, mesmo que uma conta diferente esteja autenticando a solicitação.

Hierarquia de alocação

  • Serviços de comparação de preços (CSSs) : são sites que agregam ofertas de produtos e direcionam os usuários aos sites dos varejistas para fazer compras. Ao fazer chamadas de API, as cotas são aplicadas ao grupo do CSS, domínio do CSS, conta ou subconta específica em que você faz a autenticação.

    Exemplos:

    • Um grupo de CSS chamado Europe Shopping Group (ID da conta: 10001) quer listar os domínios de CSS associados. Ao fazer a autenticação com as próprias credenciais para fazer essa chamada de API, a cota é consumida diretamente do pool de cotas do Europe Shopping Group.
    • Um domínio de CSS TopDeals CSS (ID da conta: 20002) faz a autenticação para chamar um método direcionado a uma das contas de comerciante associadas (accounts/30003) para atribuir um rótulo. A cota é consumida do pool de cotas do TopDeals CSS, não do pool da conta do comerciante.

  • Marketplaces:são plataformas on-line que hospedam vários comerciantes individuais. Eles funcionam como contas avançadas especiais que permitem criar subcontas individuais para cada um dos seus vendedores.

O diagrama a seguir mostra a hierarquia de grupos de CSS, CSS, marketplaces, contas avançadas, contas independentes e subcontas.

Um grupo do CSS é o nível de autenticação geral, com a possibilidade de CSS individuais dentro dele, contas dentro desses e subcontas como o nível mais individual.

Ajuste automático de cotas

A API Merchant tem um sistema automático de gerenciamento de cotas para serviços específicos, que ajusta os limites de cotas para comerciantes em crescimento com base no uso, na oferta e no tamanho da conta. A API Merchant recalcula essas cotas diariamente.

Os grupos de cotas incluídos nos ajustes automáticos de cotas são:

Serviços de produtos

  • Todos os grupos de cotas de métodos relacionados aos recursos products e productInputs.
  • A cota de chamadas diárias geralmente é definida como duas vezes o número de cotas de oferta que o comerciante tem. Isso pressupõe que um comerciante pode precisar atualizar cada um dos produtos até duas vezes por dia.
  • Os produtos individuais podem ser atualizados mais de duas vezes, mas as chamadas de API diárias gerais não podem exceder a cota de chamadas diárias agregada.

Serviços de contas

  • Todos os grupos de cotas de métodos relacionados aos vários recursos granulares relacionados à conta na API Merchant.
  • A cota de chamadas diárias é definida como o número máximo de subcontas permitidas para essa conta. Isso permite até duas vezes de chamadas de leitura por subconta por dia.

Serviços de fontes de dados

  • Todos os grupos de cotas de métodos relacionados aos recursos relacionados à fonte de dados na API Merchant, como list ou create, que uma conta avançada realiza nas subcontas.
  • A cota de chamadas diárias geralmente é definida como duas vezes o número de subcontas que a conta avançada tem. Isso pressupõe que um comerciante pode atualizar as fontes de dados de cada uma das subcontas até duas vezes por dia.

Somente os serviços descritos anteriormente têm ajustes automáticos de cotas. Outros serviços têm uma cota padrão, e todos os aumentos precisam ser solicitados manualmente. Para mais informações, consulte a seção Processo de aumento de cota.

O que acontece quando as cotas são excedidas

Depois que uma cota é excedida, erros aparecem nas respostas da API e na página de diagnóstico da sua conta do Merchant Center:

  • Por minuto:quota/request_rate_too_high
{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}
  • Por dia:quota/daily_limit_exceeded
{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

Os erros a seguir são limites do Merchant Center e não estão relacionados às cotas da API Merchant. Você pode tentar pedir uma cota adicional de itens, feeds ou subcontas:

  • too_many_items: cota do comerciante excedida
  • too_many_subaccounts: número máximo de subcontas atingido

Monitoramento e visibilidade

Para verificar as cotas e o uso de chamadas atuais de uma conta, chame quotas.list com o nome da conta.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Substitua:

  • ACCOUNT_ID: seu ID do Merchant Center
  • ACCESS_TOKEN: o token de autorização para fazer a chamada de API

Após uma solicitação bem-sucedida, a API retorna uma lista de quotaGroups que contêm o recurso name do grupo de cotas, as diferentes cotas e os métodos a que a cota do grupo se aplica.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

Processo de aumento de cota

Para pedir uma cota adicional, abra o formulário de contato com o suporte, selecione "Solicitação de aumento de cota" no campo obrigatório "Qual é o problema/pergunta" e preencha todos os campos obrigatórios, incluindo o ID do Merchant Center, os métodos de destino e a justificativa comercial.

  • Para recursos com cotas automáticas (products, accounts e datasources para contas avançadas) : você só pode pedir um aumento temporário para cenários especiais, como o lançamento em um novo mercado ou durante temporadas de compras de alto tráfego. Não aceitamos aumentos permanentes de cotas para esses tipos de recursos.
  • Para todos os outros recursos sem cotas automáticas:peça aumentos de cotas conforme necessário.

Recomendamos verificar suas cotas periodicamente para garantir que você tenha cota suficiente para sua implementação e ver como ela é ajustada automaticamente. Use o método quotas.list para conferir seu limite de cota diária atual, o limite de minutos e o uso diário atual de cada grupo de métodos de API.

Práticas recomendadas

A implementação dessas práticas recomendadas ajuda a garantir que sua integração seja executada sem problemas, evita erros de cota inesperados e usa os recursos do Merchant Center de maneira eficiente.

Otimizar a distribuição de solicitações

  • Distribua as solicitações de maneira uniforme:evite enviar grandes picos de solicitações. Distribua suas chamadas de API diárias uniformemente ao longo do dia para permanecer dentro dos limites de cota por minuto (quotaMinuteLimit).
  • Limitação proativa:implemente a limitação de taxa do lado do cliente (limitação) no seu aplicativo. Não dependa apenas dos servidores do Google para rejeitar o tráfego excessivo. Controle a taxa de solicitações na origem.

Tratamento de erros adequado

  • Tratar HTTP 429:seu aplicativo precisa estar preparado para tratar erros 429 "Muitas solicitações" (quota/request_rate_too_high).
  • Espera exponencial com instabilidade:ao tentar novamente solicitações com falha (especialmente após um 429), use a espera exponencial (aumento dos tempos de espera) e adicione "instabilidade" (atraso aleatório). A instabilidade evita "tempestades de repetição", em que várias instâncias de cliente tentam novamente exatamente ao mesmo tempo, sobrecarregando o servidor novamente.
  • Respeitar as dicas de repetição:se a resposta da API contiver detalhes ou cabeçalhos de repetição, use-os para determinar quando retomar as chamadas.

Minimizar chamadas redundantes

  • Evitar chamadas obsoletas (404 NOT_FOUND) : evite pedir ou excluir recursos que não existem mais. Mesmo as chamadas com falha consomem a cota da API. Monitore erros NOT_FOUND no diagnóstico da API Merchant Center para detectar o rastreamento de estado obsoleto ou a pesquisa desnecessária.
  • Verificar antes da atualização:antes de enviar uma solicitação de atualização, verifique se os dados realmente mudaram. Evite enviar atualizações que gravam os mesmos valores.
  • Usar o cache:armazene em cache as respostas de leitura (por exemplo, detalhes do produto, configurações) localmente quando apropriado para evitar chamadas get ou list repetitivas para dados inalterados.
  • Contas avançadas e subcontas:se você tiver uma conta avançada, faça a autenticação no nível da conta avançada se quiser que as chamadas sejam contabilizadas no pool compartilhado de contas avançadas.
  • Usar listSubaccounts: para contas avançadas, use accounts.listSubaccounts em vez de accounts.list. A cota accounts.list é cobrada do usuário que faz a chamada (não do ID do MC) e não fica visível nos diagnósticos padrão. listSubaccounts é contabilizado na cota da MCA.
Anterior
Overview
Avançar
Merchant Center limits