Quotas

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

L'API Merchant utilise des quotas pour garantir un environnement stable et équitable à tous les utilisateurs. Les quotas empêchent un utilisateur d'API unique 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 l'API Merchant sont gérés par le biais de groupes de quotas.

Les méthodes d'API sont associé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 liste des sources de données accounts.dataSources.list possède son propre groupe de quotas.
• Plusieurs méthodes par groupe (regroupement) : souvent, les méthodes associées sont regroupées dans un même groupe de quotas. Toutes les méthodes de ce groupe partagent les mêmes limites quotidiennes et par minute. Voici quelques exemples courants :
  • Regroupe toutes les opérations de lecture pour les méthodes et ressources associées, telles que merchant-accounts-read-methods.
  • Regrouper 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 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 regroupement HTTP intégré n'a aucune incidence sur le quota. Chaque requête individuelle d'un lot de requêtes est comptabilisée 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 des régions dédiées : les méthodes de traitement par lot des 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 régionales 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 list des quotas. Pour en savoir plus, consultez Surveillance et visibilité.

Règles relatives à la mise à jour

L'API Merchant 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 mise à jour des sous-comptes est une limite globale 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 à 12h UTC.
• Limite par minute (quotaMinuteLimit) : nombre maximal de requêtes autorisées par minute, qui contrôle le taux de 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, 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 méthode quotas.list.

Les limites quotidiennes et par minute spécifiques varient considérablement entre les différents groupes de quotas. Les opérations dont le volume attendu est plus élevé ou dont le coût système est plus faible, 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, comme les modifications de compte, peuvent avoir des limites plus basses.

Allocation et hiérarchie des quotas

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

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

• Comptes autonomes : pour les comptes autonomes qui authentifient un appel d'API, cette requête est comptabilisée dans le quota de ce compte.
  • Exemple : Le marchand Magasin de chaussures 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 Magasin de chaussures A.
• Comptes avancés : l'authentification en tant que compte avancé consomme du quota du pool du compte avancé, même lorsque vous ciblez un sous-compte.
  • Exemple : Une agence Compte administrateur pour les marchands (ID de compte avancé : 12345) gère un sous-compte Magasin de vêtements 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 à partir 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 débité du pool individuel de ce sous-compte. Il fonctionne de la même manière qu'un compte autonome, même s'il est géré par un compte avancé parent.
  • Exemple : En reprenant la configuration précédente, si Boutique de vêtements 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 individuels de Boutique de vêtements B, laissant intact le pool de l'agence parente.

Exceptions aux règles générales

Il existe quelques exceptions spécifiques aux règles générales d'attribution des quotas :

• Accounts.list : Le quota de cette méthode est débité de l'utilisateur ou du compte de service authentifié qui effectue l'appel, et non de l'ID de compte Merchant Center. Son utilisation du quota ne sera pas visible sur la page de diagnostic de l'API Merchant Center standard. Si vous disposez d'un compte avancé, nous vous recommandons d'utiliser la méthode accounts.listSubaccounts, qui est comptabilisée dans le quota de vos comptes avancés.
• Méthodes de résolution des problèmes : 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 demande.

Hiérarchie d'allocation

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

  Exemples :

  • Un groupe CSS 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 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 du CSS TopDeals, et non de celui du compte marchand.

• Places de marché : plates-formes en ligne hébergeant plusieurs marchands individuels. Ils 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 CSS, des CSS, des places de marché, des comptes avancés, des comptes individuels et des sous-comptes.

Ajustement automatique du quota

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

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

Services des produits

• Tous les groupes de quota de méthodes liés aux ressources products et productInputs.
• Le quota d'appels quotidien est généralement défini sur le double du quota 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.
• Vous pouvez mettre à jour des produits individuels plus de deux fois, mais le nombre total d'appels d'API quotidiens ne peut pas dépasser le quota d'appels quotidiens agrégé.

Services de compte

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

Services de sources de données

• Tous les groupes de quotas de méthodes liées aux ressources associées aux sources de données dans l'API Merchant, 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 le double du nombre de sous-comptes associés au 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. D'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 du quota.

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

Une fois un quota dépassé, des erreurs s'affichent dans les réponses de l'API et sur la page "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 liées aux limites de Merchant Center et ne concernent pas les quotas de l'API Merchant. Vous pouvez essayer de demander un quota supplémentaire d'articles, de flux ou de sous-comptes :

• too_many_items : quota Merchant Center 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 ressources quotaGroups 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 de quota

Pour demander un quota supplémentaire, ouvrez le formulaire de contact de l'assistance, sélectionnez "Demande d'augmentation de quota" dans le champ obligatoire "Problème/Question", puis 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, comme le lancement d'un produit sur un nouveau marché ou pendant les périodes de shopping à fort trafic. Nous n'acceptons pas les augmentations permanentes de quota 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 qu'ils sont suffisants pour votre implémentation et de voir comment ils sont ajustés 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'application de ces bonnes pratiques vous 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épartissez les requêtes de manière uniforme : évitez d'envoyer de grandes séries 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 quotas par minute (quotaMinuteLimit).
• Limitation proactive : implémentez une limitation du débit (throttling) côté client dans votre application. Ne vous fiez pas uniquement aux serveurs de Google pour refuser le trafic excessif. Contrôlez votre taux de demandes à la source.

Gestion des erreurs optimale

• Gérez les erreurs HTTP 429 : votre application doit être en mesure de gérer les erreurs 429 "Too Many Requests" (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 (temps d'attente croissant) et ajoutez une "gigue" (délai aléatoire). Le jitter empêche les "tempêtes de nouvelles tentatives", où plusieurs instances de client effectuent une nouvelle tentative exactement au même moment, surchargeant à 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.

Minimiser les appels redondants

• Évitez 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 du quota d'API. Surveillez les erreurs NOT_FOUND dans l'outil de diagnostic de l'API Merchant Center pour détecter le suivi d'état obsolète ou l'interrogation inutile.
• Vérifiez avant de mettre à jour : avant d'envoyer une demande 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) en local lorsque cela est approprié pour éviter les appels get ou list répétitifs pour les données inchangées.

Parcourir la hiérarchie des quotas et les exceptions

• Comptes avancés et sous-comptes : si vous possédez un compte avancé, authentifiez-vous au niveau du compte avancé si vous souhaitez que les appels soient comptabilisés dans le pool partagé du compte avancé.
• 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 CM) et n'est pas visible dans les diagnostics standards. listSubaccounts est décompté de votre quota de CM.