Quotas

Ce document répertorie les quotas qui s'appliquent à Merchant API.

Merchant API utilise des quotas pour garantir un environnement stable et équitable pour tous les utilisateurs. Les quotas empêchent un seul utilisateur de l'API de surcharger le système, ce qui garantit des performances élevées. Il est essentiel de comprendre ces quotas pour gérer vos données produit et développer votre activité sur Google.

Concepts généraux

Les quotas de Merchant API sont gérés par des groupes de quotas.

Les méthodes d'API sont mappées à des groupes de quotas. La structure de ce mappage peut varier :

  • Une seule méthode par groupe : certains groupes de quotas s'appliquent à une seule méthode d'API. Par exemple, la méthode de sources de données de fiches accounts.dataSources.list possède son propre groupe de quotas dédié.
  • Plusieurs méthodes par groupe (regroupement) : souvent, les méthodes associées sont regroupées dans un seul groupe de quotas. Toutes les méthodes de ce groupe partagent les mêmes limites quotidiennes et par minute. Voici quelques exemples courants :
    • Regroupement de toutes les opérations de lecture pour les méthodes et ressources associées, telles que merchant-accounts-read-methods.
    • Regroupement de toutes les opérations d'écriture pour les méthodes et ressources associées, telles que merchant-accounts-write-methods.

Chaque appel de méthode est comptabilisé une seule fois, quel que soit son type. Une requête list de 250 éléments n'est comptabilisée qu'une seule fois, et non comme 250 requêtes get.

Le traitement par lot HTTP intégré n'a aucune incidence sur le quota. Chaque requête individuelle d'un lot de requêtes est comptabilisée comme une seule requête dans le quota. Par exemple, une requête par lot contenant 500 requêtes insert est facturée comme 500 requêtes de méthode insert individuelles.

Exception pour le traitement par lot de régions dédiées : les méthodes de traitement par lot de régions spécialisées (batchCreate, batchUpdate, batchDelete) sont comptabilisées comme un seul appel d'API dans le groupe de quotas merchant_regions, quel que soit le nombre d'opérations de région contenues dans la charge utile.

Pour gérer efficacement votre intégration, vous devez examiner le groupe de quotas spécifique associé à chaque méthode d'API que vous comptez utiliser. Vous trouverez ces informations dans la méthode de liste des quotas. Pour en savoir plus, consultez Surveillance et visibilité.

Règles relatives à la mise à jour

Merchant API applique les règles suivantes en termes de mises à jour :

  • Par défaut, vous pouvez mettre à jour vos produits jusqu'à deux fois par jour. Vous devez répartir les appels de manière uniforme tout au long de la journée pour respecter le quota par minute.
  • Par défaut, vous ne pouvez mettre à jour vos sous-comptes que deux fois par jour. Votre quota quotidien de mises à jour de sous-comptes est une limite agrégée basée sur le nombre total de sous-comptes autorisés.
  • Par défaut, vous ne pouvez appeler les méthodes de source de données pour vos sous-comptes, telles que list ou create, que deux fois par sous-compte et par jour.

Les quotas de débit

Chaque groupe de quotas comporte deux types de limites (et d'utilisation quotidienne) :

  • Limite quotidienne (quotaLimit) : nombre maximal de requêtes autorisées par jour. Les limites de quota quotidiennes sont réinitialisées à 12h00 UTC.
  • Limite par minute (quotaMinuteLimit) : nombre maximal de requêtes autorisées par minute, qui contrôle le débit des requêtes. Les limites de quota par minute utilisent une fenêtre glissante, où la période d'application commence au moment où le premier appel d'API pour cette méthode et cette ressource est effectué. Par exemple, si vous effectuez un appel à 10h01min30s, la fenêtre de quota par minute pour cette méthode s'exécute jusqu'à 10h02min30s.
  • Utilisation quotidienne (quotaUsage) : nombre de requêtes déjà effectuées et comptabilisées dans la limite quotidienne pour le jour en cours. Si le champ est manquant, cela signifie qu'aucun quota n'a encore été consommé pour ce groupe.

Vous trouverez les trois champs décrits précédemment (quotaLimit, quotaMinuteLimit, et quotaUsage) dans la réponse de la quotas.list méthode.

Les limites quotidiennes et par minute spécifiques varient considérablement d'un groupe de quotas à l'autre. Les opérations dont le volume attendu est plus élevé ou dont le coût système est inférieur, comme la lecture des données produit, ont généralement des limites plus élevées. À l'inverse, les opérations plus intensives ou sensibles, telles que les modifications de compte, peuvent avoir des limites inférieures.

Allocation et hiérarchie des quotas

Cette section explique au nom de qui Merchant API suit et applique l'utilisation des quotas :

En général, le quota est facturé en fonction de l'utilisateur qui effectue la requête API.

  • Comptes individuels : pour les comptes individuels qui authentifient un appel d'API, cette requête est comptabilisée dans le quota de ce compte.
    • Exemple : Un marchand, Shoe Store A (ID de compte : 12345), s'authentifie à l'aide de son propre compte de service pour appeler products.insert en ciblant son propre compte (accounts/12345). Le quota est consommé à partir du pool de quotas de Shoe Store A.
  • Comptes avancés : l'authentification en tant que compte avancé consomme un quota du pool du compte avancé, même lorsque vous ciblez un sous-comp5}.
    • Exemple : Une agence, Retail Management Account (ID de compte avancé : 12345), gère un sous-compte, Clothing Store B (ID de compte : 11111). L'agence s'authentifie à l'aide de ses propres identifiants et appelle products.insert en ciblant Clothing Store B (accounts/11111). Le quota est consommé à partir du pool de l'agence parente (ID de compte avancé : 12345), et non du pool du sous-compte.
  • Sous-comptes : lorsque les appels d'API sont authentifiés à l'aide des identifiants d'un sous-compte, le quota est facturé au pool individuel de ce sous-compte. Le fonctionnement est le même que pour un compte individuel, même s'il est géré par un compte avancé parent.
    • Exemple : En utilisant la même configuration que précédemment, si Clothing Store B (ID de compte : 11111) s'authentifie à l'aide d'identifiants configurés spécifiquement pour son sous-compte afin d'appeler products.insert en ciblant son propre compte (accounts/11111), le quota est consommé à partir du pool de quotas individuel de Clothing Store B, laissant intact le pool de l'agence parente.

Exceptions aux règles générales

Il existe quelques exceptions spécifiques qui s'appliquent aux règles générales d'allocation de quotas :

  • Accounts.list : Le quota de cette méthode est facturé à l'utilisateur authentifié ou au compte de service qui effectue l'appel, et non à l'ID de compte Merchant Center. Son utilisation du quota ne sera pas visible sur la page de diagnostic standard de l'API Merchant Center. Si vous disposez d'un compte avancé, nous vous recommandons d'utiliser la accounts.listSubaccounts méthode, qui est comptabilisée dans le quota de vos comptes avancés.
  • Méthodes Issueresolution : ces méthodes sont toujours comptabilisées dans le quota du compte dont les problèmes sont demandés, même si un autre compte authentifie la requête.

Hiérarchie d'allocation

  • Services de comparateur de prix (SCP) : les SCP sont des sites Web qui regroupent des offres de produits et dirigent les utilisateurs vers les sites Web des marchands pour effectuer des achats. Lorsque vous effectuez des appels d'API, les quotas sont appliqués au groupe CSS, au domaine CSS, au compte ou au sous-compte spécifique pour lequel vous vous authentifiez.

    Exemples :

    • Un groupe de SCP nommé Europe Shopping Group (ID de compte : 10001) souhaite lister ses domaines CSS associés. En s'authentifiant avec ses propres identifiants pour effectuer cet appel d'API, le quota est consommé directement à partir du pool de quotas de Europe Shopping Group.
    • Un domaine CSS, TopDeals CSS (ID de compte : 20002), s'authentifie pour appeler une méthode ciblant l'un de ses comptes marchands associés (accounts/30003) afin d'attribuer un libellé. Le quota est consommé à partir du pool de quotas de TopDeals CSS, et non du pool du compte marchand.

  • Places de marché : les places de marché sont des plates-formes en ligne qui hébergent plusieurs marchands individuels. Elles fonctionnent comme des comptes avancés spéciaux qui vous permettent de créer des sous-comptes individuels pour chacun de vos vendeurs.

Le schéma suivant illustre la hiérarchie des groupes de SCP, des SCP, des places de marché, des comptes avancés, des comptes individuels et des sous-comptes.

Un groupe CSS est le niveau d'authentification global. Il peut contenir des CSS individuels, des comptes dans ces CSS et des sous-comptes comme niveau le plus individuel.

Ajustement automatique des quotas

Merchant API dispose d'un système de gestion automatique des quotas pour des services spécifiques, qui ajuste les limites de quota pour les marchands en croissance en fonction de votre utilisation, de votre offre et de la taille de votre compte. Merchant API recalcule ces quotas quotidiennement.

Les groupes de quotas inclus dans les ajustements automatiques des quotas sont les suivants :

Services des produits

  • Tous les groupes de quotas des méthodes liées aux ressources products et productInputs.
  • Le quota d'appels quotidien est généralement défini sur deux fois le nombre de quotas d'offres dont dispose le marchand. Cela suppose qu'un marchand peut avoir besoin de mettre à jour chacun de ses produits jusqu'à deux fois par jour.
  • Les produits individuels peuvent être mis à jour plus de deux fois, mais le nombre total d'appels d'API quotidiens ne peut pas dépasser le quota d'appels quotidien agrégé.

Services relatifs aux comptes

  • Tous les groupes de quotas des méthodes liées aux différentes ressources granulaires associées aux comptes dans Merchant API.
  • Le quota d'appels quotidien est défini sur le nombre maximal de sous-comptes autorisés pour ce compte. Cela permet d'effectuer jusqu'à deux fois plus d'appels de lecture par sous-compte et par jour.

Services de sources de données

  • Tous les groupes de quotas des méthodes liées aux ressources associées aux sources de données dans Merchant API, telles que list ou create, qu'un compte avancé effectue sur ses sous-comptes.
  • Le quota d'appels quotidien est généralement défini sur deux fois le nombre de sous-comptes dont dispose le compte avancé. Cela suppose qu'un marchand peut mettre à jour les sources de données de chacun de ses sous-comptes jusqu'à deux fois par jour.

Seuls les services décrits précédemment bénéficient d'ajustements automatiques des quotas. Les autres services disposent d'un quota par défaut, et toute augmentation doit être demandée manuellement. Pour en savoir plus, consultez la section Processus d'augmentation des quotas.

Que se passe-t-il lorsque les quotas sont dépassés ?

Une fois qu'un quota a été dépassé, des erreurs s'affichent dans les réponses de l'API et sur la page de diagnostic de votre compte Merchant Center :

  • Par minute : 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"
                }
            }
        ]
    }
}
  • Par jour : 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"
                }
            }
        ]
    }
}

Les erreurs suivantes sont des limites Merchant Center et ne sont pas liées aux quotas de Merchant API. Vous pouvez essayer de demander des quotas supplémentaires d'articles, de flux ou de sous-comptes :

  • too_many_items : quota de marchand dépassé
  • too_many_subaccounts : nombre maximal de sous-comptes atteint

Surveillance et visibilité

Pour vérifier les quotas d'appels et l'utilisation actuels d'un compte, appelez quotas.list avec le nom du compte.

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

Remplacez les éléments suivants :

  • ACCOUNT_ID : votre ID Merchant Center
  • ACCESS_TOKEN: jeton d'autorisation pour effectuer l'appel d'API

Si la requête aboutit, l'API renvoie une liste de quotaGroups ressources contenant la ressource name du groupe de quotas, les différents quotas et les méthodes auxquelles le quota de groupe s'applique.

{
    "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"
        }
    ]
}

Processus d'augmentation des quotas

Pour demander un quota supplémentaire, ouvrez le formulaire Contacter l'assistance, sélectionnez "Demande d'augmentation de quota" dans le champ obligatoire "Quel est le problème/la question ?" et remplissez tous les champs obligatoires, y compris votre ID Merchant Center, les méthodes cibles et la justification commerciale.

  • Pour les ressources avec des quotas automatiques (products, accounts et datasources pour les comptes avancés) : vous ne pouvez demander qu'une augmentation temporaire pour des scénarios spéciaux, tels que le lancement sur un nouveau marché ou pendant les périodes de forte affluence. Nous n'acceptons pas les augmentations de quota permanentes pour ces types de ressources.
  • Pour toutes les autres ressources sans quotas automatiques : demandez des augmentations de quota selon vos besoins.

Nous vous recommandons de vérifier régulièrement vos quotas pour vous assurer que vous disposez d'un quota suffisant pour votre implémentation et de voir comment votre quota est ajusté automatiquement. Utilisez la méthode quotas.list pour afficher votre limite de quota quotidienne actuelle, votre limite par minute et votre utilisation quotidienne actuelle pour chaque groupe de méthodes d'API.

Bonnes pratiques

L'implémentation de ces bonnes pratiques permet de garantir le bon fonctionnement de votre intégration, d'éviter les erreurs de quota inattendues et d'utiliser efficacement les ressources Merchant Center.

Optimiser la distribution des requêtes

  • Répartir les requêtes de manière uniforme : évitez d'envoyer de grandes rafales de requêtes. Répartissez vos appels d'API quotidiens de manière uniforme tout au long de la journée pour respecter les limites de quota par minute (quotaMinuteLimit).
  • Limitation proactive : implémentez une limitation du débit côté client (limitation) dans votre application. Ne comptez pas uniquement sur les serveurs de Google pour rejeter le trafic excessif. Contrôlez votre taux de demandes à la source.

Gestion des erreurs en douceur

  • Gérer l'erreur HTTP 429 : votre application doit être prête à gérer les erreurs 429 "Trop de requêtes" (quota/request_rate_too_high).
  • Intervalle exponentiel entre les tentatives avec gigue : lorsque vous relancez des requêtes ayant échoué (en particulier après une erreur 429), utilisez un intervalle exponentiel entre les tentatives (augmentation des temps d'attente) et ajoutez une "gigue" (délai aléatoire). La gigue empêche les "tempêtes de tentatives", où plusieurs instances client tentent de relancer la requête exactement au même moment, ce qui surcharge à nouveau le serveur.
  • Respecter les indications de nouvelle tentative : si la réponse de l'API contient des détails ou des en-têtes de nouvelle tentative, utilisez-les pour déterminer quand reprendre les appels.

Réduire au maximum les appels redondants

  • Éviter les appels obsolètes (404 NOT_FOUND) : évitez de demander ou de supprimer des ressources qui n'existent plus. Même les appels ayant échoué consomment un quota d'API. Surveillez les erreurs NOT_FOUND dans l'outil Diagnostic de l'API Merchant Center pour détecter le suivi d'état obsolète ou l'interrogation inutile.
  • Vérifier avant de mettre à jour : avant d'envoyer une requête de mise à jour, vérifiez si les données ont réellement changé. Évitez d'envoyer des mises à jour qui écrivent les mêmes valeurs.
  • Utiliser la mise en cache : mettez en cache les réponses de lecture (par exemple, les détails du produit, les paramètres) localement, le cas échéant, pour éviter les appels get ou list répétitifs pour les données inchangées.
  • Comptes avancés et sous-comptes : si vous disposez d'un compte avancé, authentifiez-vous au niveau du compte avancé si vous souhaitez que les appels soient comptabilisés dans le pool partagé des comptes avancés.
  • Utiliser listSubaccounts: Pour les comptes avancés, utilisez accounts.listSubaccounts au lieu de accounts.list. Le quota accounts.list est facturé à l'utilisateur appelant (et non à l'ID MC) et n'est pas visible dans les diagnostics standards. listSubaccounts est comptabilisé dans votre quota MC.
Précédent
Overview
Suivant
Merchant Center limits