Cotas

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

A API Merchant usa cotas para 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:

• Um único método por grupo:alguns grupos de cotas se aplicam a um único método de API. Por exemplo, o método de listagem de fontes de dados accounts.dataSources.list tem um grupo de cota dedicado.
• Vários métodos por grupo (pacotes): geralmente, 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. Alguns exemplos comuns:
  • Agrupando todas as operações de leitura para métodos e recursos relacionados, como merchant-accounts-read-methods.
  • Agrupando 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, independente do tipo. Uma solicitação list de 250 itens é contabilizada apenas uma vez, não como 250 solicitações get.

O agrupamento HTTP integrado não influencia a cota. Cada solicitação individual em um lote de solicitações conta como uma em relação à cota. Por exemplo, uma solicitação em lote com 500 solicitações insert é cobrada como 500 solicitações individuais do método insert.

Exceção para o agrupamento em lote de regiões dedicadas:os métodos especializados de agrupamento em lote de regiões (batchCreate, batchUpdate, batchDelete) contam como uma única chamada de API no grupo de cota merchant_regions, independente do número de operações de região contidas no payload.

Para gerenciar sua integração de forma 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 Monitoring e Visibility.

Atualizar política

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

• Por padrão, é possível atualizar seus produtos até duas vezes por dia. Distribua as chamadas uniformemente ao longo do dia para obedecer à cota por minuto.
• Por padrão, só é possível atualizar as 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. As cotas por minuto usam uma janela rotativa, 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 10h01min30s, a janela de cota por minuto desse método vai até as 10h02min30s.
• Uso diário (quotaUsage): o número de solicitações que já foram feitas e contadas no limite diário do dia atual. Se o campo estiver faltando, nenhuma cota foi consumida para esse grupo ainda.

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

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 leitura de dados de produtos, geralmente têm limites mais altos. Por outro lado, operações mais intensivas ou sensíveis, como modificações na conta, podem ter limites menores.

Alocação e hierarquia de cota

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

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:uma loja Loja de sapatos A (ID da conta: 12345) se autentica usando a própria conta de serviço para chamar products.insert segmentando a própria conta (accounts/12345). A cota é consumida do pool de cotas da Loja de sapatos A.
• Contas avançadas:a autenticação como uma conta avançada consome 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 segmentando a Loja de roupas B (accounts/11111). A cota é consumida do pool da agência principal (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 do pool individual dessa subconta. Ela funciona da mesma forma que uma conta independente, mesmo sendo gerenciada por uma conta avançada principal.
  • 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 dela e chamar products.insert segmentando a própria conta (accounts/11111), a cota será consumida do pool individual da Loja de roupas B, deixando o pool da agência principal intacto.

Exceções às regras gerais

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

• Accounts.list: a cota para esse 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 vai aparecer na página de diagnóstico da API Merchant Center padrão. Se você tiver uma conta avançada, recomendamos usar o método accounts.listSubaccounts, que conta para sua cota de contas avançadas.
• Métodos de Issueresolution: 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 (CSS): 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, conta ou subconta específica em que você faz a autenticação.

  Exemplos:

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

• Marketplaces:são plataformas on-line que hospedam vários comerciantes individuais. Elas 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 do CSS, CSS, marketplaces, contas avançadas, contas independentes e subcontas.

Ajuste automático de cota

A API Merchant tem um sistema automático de gerenciamento de cota para serviços específicos, que ajusta os limites de cota 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 são:

Serviços de produtos

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

Serviços de contas

• Todos os grupos de cota de métodos relacionados aos vários recursos granulares relacionados à conta na API Merchant.
• A cota diária de chamadas é 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 cota de métodos relacionados aos recursos da fonte de dados na API Merchant, como list ou create, que uma conta avançada realiza nas subcontas.
• A cota diária de chamadas 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.

Apenas os serviços descritos anteriormente têm ajustes automáticos de cota. Outros serviços têm uma cota padrão, e 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, os 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 de chamadas e o uso 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.

Quando uma solicitação é bem-sucedida, a API retorna uma lista de recursos 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 solicitar mais cota, abra o formulário de contato com o suporte, selecione "Solicitação de aumento de cota" no campo obrigatório "Qual é o problema/a dúvida" e preencha todos os campos obrigatórios, incluindo seu ID do Merchant Center, os métodos de segmentação e a justificativa comercial.

• Para recursos com cotas automáticas (products, accounts e datasources para contas avançadas): só é possível solicitar um aumento temporário para cenários especiais, como o lançamento em um novo mercado ou durante temporadas de compras com muito tráfego. Não aceitamos aumentos permanentes de cota para esses tipos de recursos.
• Para todos os outros recursos sem cotas automáticas:solicite aumentos de cota conforme necessário.

Recomendamos verificar suas cotas periodicamente para garantir que você tenha o suficiente para sua implementação e ver como elas são ajustadas automaticamente. Use o método quotas.list para conferir seu limite diário atual, o limite por minuto e o uso diário atual de cada grupo de métodos da API.

Práticas recomendadas

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

Otimizar a distribuição de solicitações

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

Tratamento de erros elegante

• Trate o HTTP 429:seu aplicativo precisa estar preparado para lidar com erros 429 Too Many Requests (quota/request_rate_too_high).
• Espera exponencial com instabilidade:ao tentar novamente solicitações com falha (principalmente após um erro 429), use a espera exponencial (aumentando os tempos de espera) e adicione "instabilidade" (atraso aleatório). A instabilidade evita "tempestades de novas tentativas", em que várias instâncias de cliente tentam novamente exatamente ao mesmo tempo, sobrecarregando o servidor novamente.
• Respeite as dicas de nova tentativa:se a resposta da API contiver detalhes ou cabeçalhos de nova tentativa, use-os para determinar quando retomar as chamadas.

Minimizar chamadas redundantes

• Evite chamadas obsoletas (404 NOT_FOUND): evite solicitar ou excluir recursos que não existem mais. Mesmo as chamadas com falha consomem a cota da API. Monitore erros de NOT_FOUND no diagnóstico da API do Merchant Center para detectar rastreamento de estado desatualizado ou sondagem desnecessária.
• Verifique antes de atualizar:antes de enviar uma solicitação de atualização, confira se os dados realmente mudaram. Evite enviar atualizações que gravam os mesmos valores.
• Use cache:armazene em cache as respostas de leitura (por exemplo, detalhes do produto, configurações) localmente quando apropriado para evitar chamadas repetitivas de get ou list para dados inalterados.

Navegar pela hierarquia e exceções de cota

• Contas avançadas e subcontas:se você tiver uma conta avançada, faça a autenticação no nível dela se quiser que as chamadas sejam contabilizadas no pool compartilhado de contas avançadas.
• Use listSubaccounts:para contas avançadas, use accounts.listSubaccounts em vez de accounts.list. A cota de accounts.list é cobrada do usuário que faz a chamada (não do ID da MC) e não fica visível nos diagnósticos padrão. listSubaccounts conta na sua cota da MCA.