Kontingente

In diesem Dokument sind die Kontingente für die Merchant API aufgeführt.

Die Merchant API verwendet Kontingente, um für alle Nutzer eine stabile und faire Umgebung zu schaffen. Kontingente verhindern, dass ein einzelner API-Nutzer das System übermäßig belastet, und sorgen so für eine hohe Leistung. Um Ihre Produktdaten optimal zu verwalten und Ihren Umsatz auf Google zu steigern, sollten Sie sich mit diesen Kontingenten vertraut machen.

Allgemeine Konzepte

Merchant API-Kontingente werden über Kontingentgruppen verwaltet.

API-Methoden werden Kontingentgruppen zugeordnet. Die Struktur dieser Zuordnung kann variieren:

  • Eine Methode pro Gruppe:Einige Kontingentgruppen gelten für eine einzelne API-Methode. Die Methode zum Auflisten von Datenquellen für Einträge accounts.dataSources.list hat beispielsweise eine eigene Kontingentgruppe.
  • Mehrere Methoden pro Gruppe (Bündelung): Häufig werden zusammengehörige Methoden in einer einzigen Kontingentgruppe gebündelt. Für alle Methoden in dieser Gruppe gelten dieselben Tages- und Minutengrenzwerte. Häufige Beispiele:
    • Alle Lesevorgänge für zugehörige Methoden und Ressourcen wie merchant-accounts-read-methods werden gruppiert.
    • Alle Schreibvorgänge für zugehörige Methoden und Ressourcen werden gruppiert, z. B. merchant-accounts-write-methods.

Jeder Methodenaufruf wird einmal gezählt, unabhängig vom Typ. Eine list-Anfrage mit 250 Elementen wird nur einmal gezählt, nicht als 250 get-Anfragen.

Das integrierte HTTP-Batching hat keinen Einfluss auf das Kontingent. Jede einzelne Anfrage in einem Batch von Anfragen wird als eine Anfrage auf das Kontingent angerechnet. Eine Batchanfrage mit 500 insert-Anfragen wird beispielsweise als 500 einzelne insert-Methodenanfragen abgerechnet.

Ausnahme für Batching in dedizierten Regionen:Spezialisierte Batch-Methoden für Regionen (batchCreate, batchUpdate, batchDelete) werden unabhängig von der Anzahl der in der Nutzlast enthaltenen regionalen Vorgänge als ein einziger API-Aufruf für die Kontingentgruppe merchant_regions gezählt.

Damit Sie Ihre Integration effektiv verwalten können, sollten Sie die spezifische Kontingentgruppe für jede API-Methode, die Sie verwenden möchten, prüfen. Diese Details finden Sie in der Methode „quotas.list“. Weitere Informationen finden Sie unter Monitoring und Sichtbarkeit.

Richtlinie aktualisieren

Für die Merchant API gelten in Bezug auf Aktualisierungen die folgenden Richtlinien:

  • Standardmäßig können Sie Ihre Produkte bis zu zweimal täglich aktualisieren. Sie sollten die Anrufe gleichmäßig über den Tag verteilen, um das Kontingent pro Minute einzuhalten.
  • Standardmäßig können Sie Ihre untergeordneten Konten nur zweimal pro Tag aktualisieren. Ihr tägliches Kontingent für die Aktualisierung von Unterkonten ist eine aggregierte Beschränkung, die auf der Gesamtzahl der zulässigen Unterkonten basiert.
  • Standardmäßig können Sie Datenquellenmethoden für Ihre Unterkonten wie list oder create nur zweimal pro Unterkonto und Tag aufrufen.

Ratenkontingente

Für jede Kontingentgruppe gibt es zwei Arten von Limits (und täglicher Nutzung):

  • Tageslimit (quotaLimit): Die maximale Anzahl von Anfragen, die pro Tag zulässig sind. Die Tageskontingentlimits werden um 12:00 Uhr UTC zurückgesetzt.
  • Limit pro Minute (quotaMinuteLimit): Die maximale Anzahl von Anfragen, die pro Minute zulässig sind. Damit wird die Rate der Anfragen gesteuert. Die Kontingente pro Minute verwenden ein gleitendes Zeitfenster. Der Zeitraum für die Durchsetzung beginnt mit dem ersten API-Aufruf für diese Methode und Ressource. Wenn Sie beispielsweise einen Aufruf um 10:01:30 Uhr ausführen, läuft das Kontingentfenster pro Minute für diese Methode bis 10:02:30 Uhr.
  • Tägliche Nutzung (quotaUsage): Die Anzahl der Anfragen, die bereits gestellt wurden und auf das Tageslimit für den aktuellen Tag angerechnet werden. Wenn das Feld fehlt, wurde für diese Gruppe noch kein Kontingent verbraucht.

Die drei oben beschriebenen Felder (quotaLimit, quotaMinuteLimit und quotaUsage) finden Sie in der Antwort der Methode quotas.list.

Die spezifischen Tages- und Minutengrenzen variieren erheblich zwischen den verschiedenen Kontingentgruppen. Vorgänge mit einem höheren erwarteten Volumen oder niedrigeren Systemkosten, z. B. das Lesen von Produktdaten, haben in der Regel höhere Limits. Umgekehrt können für intensivere oder sensiblere Vorgänge wie Kontoänderungen niedrigere Limits gelten.

Kontingentzuweisung und ‑hierarchie

In diesem Abschnitt wird erläutert, für wen die Merchant API die Kontingentnutzung erfasst und anwendet:

Im Allgemeinen wird das Kontingent basierend auf dem Nutzer berechnet, der die API-Anfrage stellt.

  • Eigenständige Konten:Wenn ein API-Aufruf mit einem eigenständigen Konto authentifiziert wird, wird die Anfrage auf das Kontingent dieses Kontos angerechnet.
    • Beispiel:Ein Händler Schuhgeschäft A (Konto-ID: 12345) authentifiziert sich mit seinem eigenen Dienstkonto, um products.insert für sein eigenes Konto (accounts/12345) aufzurufen. Das Kontingent wird aus dem Kontingentpool von Schuhgeschäft A verbraucht.
  • Erweiterte Konten:Wenn Sie sich als erweitertes Konto authentifizieren, wird das Kontingent aus dem Pool des erweiterten Kontos verbraucht, auch wenn Sie auf ein Unterkonto abzielen.
    • Beispiel:Eine Agentur mit einem Verwaltungskonto für Einzelhändler (erweiterte Konto-ID: 12345) verwaltet ein Unterkonto Bekleidungsgeschäft B (Konto-ID: 11111). Die Agentur authentifiziert sich mit ihren eigenen Anmeldedaten und ruft products.insert auf, wobei Bekleidungsgeschäft B (accounts/11111) als Ziel angegeben wird. Das Kontingent wird aus dem Pool des übergeordneten Agenturkonto (erweiterte Konto-ID: 12345) und nicht aus dem Pool des untergeordneten Kontos verwendet.
  • Unterkonten:Wenn API-Aufrufe mit den Anmeldedaten eines Unterkontos authentifiziert werden, wird das Kontingent dem individuellen Pool dieses Unterkontos belastet. Es funktioniert genauso wie ein eigenständiges Konto, auch wenn es von einem übergeordneten erweiterten Konto verwaltet wird.
    • Beispiel:Wenn Bekleidungsgeschäft B (Konto-ID: 11111) mit derselben Einrichtung wie oben beschrieben authentifiziert wird, um products.insert für das eigene Konto (accounts/11111) aufzurufen, wird das Kontingent aus dem individuellen Kontingentpool von Bekleidungsgeschäft B verwendet. Der Pool der übergeordneten Agentur bleibt unberührt.

Ausnahmen von den allgemeinen Regeln

Für die allgemeinen Regeln für die Kontingentzuweisung gelten einige spezifische Ausnahmen:

  • Accounts.list: Das Kontingent für diese Methode wird dem authentifizierten Nutzer oder Dienstkonto in Rechnung gestellt, der bzw. das den Aufruf ausführt, nicht der Merchant Center-Konto-ID. Die Kontingentnutzung ist nicht auf der standardmäßigen Diagnoseseite der Merchant Center API sichtbar. Wenn Sie ein erweitertes Konto haben, empfehlen wir die Verwendung der Methode accounts.listSubaccounts, die auf Ihr Kontingent für erweiterte Konten angerechnet wird.
  • Methoden zur Problembehebung: Diese Methoden werden immer auf das Kontingent des Kontos angerechnet, für das die Probleme angefordert werden, auch wenn die Anfrage von einem anderen Konto authentifiziert wird.

Zuweisungshierarchie

  • Preisvergleichsportale: Preisvergleichsportale sind Websites, auf denen Produktangebote zusammengefasst werden und Nutzer zu den Websites von Einzelhändlern weitergeleitet werden, um Käufe zu tätigen. Bei API-Aufrufen werden Kontingente auf die jeweilige Preisvergleichsportal-Gruppe, Preisvergleichsportal-Domain, das Konto oder das Unterkonto angewendet, für das Sie sich authentifizieren.

    Beispiele:

    • Eine Preisvergleichsportal-Gruppe mit dem Namen Europe Shopping Group (Konto-ID: 10001) möchte die zugehörigen Preisvergleichsportal-Domains auflisten. Da die Authentifizierung für diesen API-Aufruf mit den eigenen Anmeldedaten erfolgt, wird das Kontingent direkt aus dem Kontingentpool der Europe Shopping Group (Europäische Shopping-Gruppe) verwendet.
    • Eine Preisvergleichsportal-Domain TopDeals CSS (Konto-ID: 20002) wird authentifiziert, um eine Methode aufzurufen, die auf eines der zugehörigen Händlerkonten (accounts/30003) ausgerichtet ist, um ein Label zuzuweisen. Das Kontingent wird aus dem Kontingentpool des Preisvergleichsportals für Top-Angebote und nicht aus dem des Merchant Center-Kontos verwendet.

  • Marktplätze:Marktplätze sind Onlineplattformen, auf denen mehrere einzelne Händler vertreten sind. Sie funktionieren als spezielle erweiterte Konten, mit denen Sie für jeden Ihrer Verkäufer separate Unterkonten erstellen können.

Das folgende Diagramm zeigt die Hierarchie von Preisvergleichsportal-Gruppen, Preisvergleichsportalen, Marktplätzen, erweiterten Konten, eigenständigen Konten und Unterkonten.

Eine Preisvergleichsportal-Gruppe ist die übergeordnete Authentifizierungsebene. Darunter können sich einzelne Preisvergleichsportale, Konten und Unterkonten als die individuellste Ebene befinden.

Automatische Kontingentanpassung

Die Merchant API verfügt über ein automatisches Kontingentverwaltungssystem für bestimmte Dienste, das die Kontingentlimits für wachsende Händler basierend auf Ihrer Nutzung, Ihrem Angebot und Ihrer Kontogröße anpasst. Die Merchant API berechnet diese Kontingente täglich neu.

Die Kontingentgruppen, die in automatischen Kontingentanpassungen enthalten sind:

Produktdienste

  • Alle Kontingentgruppen von Methoden, die sich auf die Ressourcen products und productInputs beziehen.
  • Das tägliche Anrufkontingent entspricht in der Regel dem doppelten Angebotskontingent des Händlers. Dabei wird davon ausgegangen, dass ein Händler jedes seiner Produkte bis zu zweimal täglich aktualisieren muss.
  • Einzelne Produkte können mehr als zweimal aktualisiert werden, aber die Gesamtzahl der täglichen API-Aufrufe darf das aggregierte tägliche Aufrufkontingent nicht überschreiten.

Kontodienste

  • Alle Kontingentgruppen von Methoden, die sich auf die verschiedenen detaillierten kontobezogenen Ressourcen in der Merchant API beziehen.
  • Das tägliche Anrufkontingent ist auf die maximale Anzahl von Unterkonten festgelegt, die für dieses Konto zulässig sind. So sind bis zu zwei Leseaufrufe pro Unterkonto und Tag möglich.

Dienste für Datenquellen

  • Alle Kontingentgruppen von Methoden, die sich auf die Datenquellen-bezogenen Ressourcen in der Merchant API beziehen, z. B. list oder create, die ein erweitertes Konto für seine Unterkonten ausführt.
  • Das tägliche Anrufkontingent ist in der Regel auf das Doppelte der Anzahl der Unterkonten des erweiterten Kontos festgelegt. Dabei wird davon ausgegangen, dass ein Händler die Datenquellen seiner Unterkonten bis zu zweimal täglich aktualisieren kann.

Nur für die oben beschriebenen Dienste werden Kontingente automatisch angepasst. Für andere Dienste gilt ein Standardkontingent und Erhöhungen müssen manuell angefordert werden. Weitere Informationen finden Sie im Abschnitt Prozess zur Kontingenterhöhung.

Was passiert, wenn Kontingente überschritten wurden?

Wenn ein Kontingent überschritten wurde, werden in den API-Antworten und auf der Seite „Diagnose“ in Ihrem Merchant Center-Konto Fehler angezeigt:

  • Pro 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"
                }
            }
        ]
    }
}
  • Pro Tag: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"
                }
            }
        ]
    }
}

Die folgenden Fehler sind Merchant Center-Beschränkungen und haben nichts mit Merchant API-Kontingenten zu tun. Sie können versuchen, ein zusätzliches Kontingent an Artikeln, Feeds oder Unterkonten anzufordern:

  • too_many_items: Händlerkontingent überschritten
  • too_many_subaccounts: Maximale Anzahl von untergeordneten Konten erreicht

Monitoring und Sichtbarkeit

Wenn Sie die aktuellen Anrufkontingente und die Nutzung für ein Konto prüfen möchten, rufen Sie quotas.list mit dem Namen des Kontos auf.

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

Ersetzen Sie Folgendes:

  • ACCOUNT_ID: Ihre Merchant Center-ID
  • ACCESS_TOKEN: das Autorisierungstoken für den API-Aufruf

Bei einer erfolgreichen Anfrage gibt die API eine Liste von quotaGroups-Ressourcen zurück, die die Ressource name der Kontingentgruppe, die verschiedenen Kontingente und die Methoden enthalten, auf die das Gruppenkontingent angewendet wird.

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

Kontingenterhöhung

Wenn Sie zusätzliches Kontingent anfordern möchten, öffnen Sie das Supportkontaktformular, wählen Sie im Feld „Was ist das Problem/die Frage?“ die Option „Anfrage zur Kontingenterhöhung“ aus und füllen Sie alle erforderlichen Felder aus, einschließlich Ihrer Merchant Center-ID, der Zielmethoden und der geschäftlichen Begründung.

  • Für Ressourcen mit automatischen Kontingenten (products, accounts und datasources für erweiterte Konten): Sie können nur eine vorübergehende Erhöhung für spezielle Szenarien wie die Einführung in einem neuen Markt oder während der Shopping-Saison mit hohem Traffic beantragen. Wir akzeptieren keine dauerhaften Kontingenterhöhungen für diese Arten von Ressourcen.
  • Für alle anderen Ressourcen ohne automatisches Kontingent:Fordern Sie bei Bedarf Kontingenterhöhungen an.

Wir empfehlen, Ihre Kontingente regelmäßig zu prüfen, um sicherzustellen, dass Sie genügend Kontingent für Ihre Implementierung haben, und zu sehen, wie Ihr Kontingent automatisch angepasst wird. Mit der Methode quotas.list können Sie Ihr aktuelles tägliches Kontingentlimit, das Minutenlimit und die aktuelle tägliche Nutzung für jede API-Methodengruppe aufrufen.

Best Practices

Wenn Sie diese Best Practices implementieren, sorgen Sie für einen reibungslosen Ablauf Ihrer Integration, vermeiden unerwartete Kontingentfehler und nutzen Merchant Center-Ressourcen effizient.

Verteilung von Anfragen optimieren

  • Anfragen gleichmäßig verteilen:Vermeiden Sie es, viele Anfragen gleichzeitig zu senden. Verteilen Sie Ihre täglichen API-Aufrufe gleichmäßig über den Tag, um die Kontingentlimits pro Minute (quotaMinuteLimit) nicht zu überschreiten.
  • Proaktive Drosselung:Implementieren Sie eine clientseitige Ratenbegrenzung (Drosselung) in Ihrer Anwendung. Verlassen Sie sich nicht nur auf die Server von Google, um übermäßigen Traffic abzulehnen. Kontrollieren Sie die Anforderungsrate an der Quelle.

Reibungslose Fehlerbehandlung

  • HTTP 429-Fehler behandeln:Ihre Anwendung muss darauf vorbereitet sein, 429-Fehler vom Typ „Too Many Requests“ (quota/request_rate_too_high) zu verarbeiten.
  • Exponentieller Backoff mit Jitter:Wenn Sie fehlgeschlagene Anfragen noch einmal senden (insbesondere nach einem 429-Fehler), verwenden Sie den exponentiellen Backoff (zunehmende Wartezeiten) und fügen Sie „Jitter“ (zufällige Verzögerung) hinzu. Jitter verhindert „Retry-Stürme“, bei denen mehrere Client-Instanzen genau gleichzeitig wiederholt werden und den Server erneut überlasten.
  • Wiederholungs-Hinweise beachten:Wenn die API-Antwort Wiederholungsdetails oder ‑Header enthält, verwenden Sie diese, um zu bestimmen, wann die Aufrufe fortgesetzt werden sollen.

Redundante Anrufe minimieren

  • Veraltete Anrufe vermeiden (404 NOT_FOUND): Vermeiden Sie das Anfordern oder Löschen von Ressourcen, die nicht mehr vorhanden sind. Auch fehlgeschlagene Aufrufe verbrauchen API-Kontingent. Überwachen Sie NOT_FOUND-Fehler in der Merchant Center API-Diagnose, um veraltetes Status-Tracking oder unnötiges Polling zu erkennen.
  • Vor dem Aktualisieren prüfen:Bevor Sie eine Aktualisierungsanfrage senden, sollten Sie prüfen, ob sich die Daten tatsächlich geändert haben. Vermeiden Sie das Senden von Updates, die dieselben Werte schreiben.
  • Caching verwenden:Antworten auf Leseanfragen (z.B. Produktdetails, Einstellungen) sollten bei Bedarf lokal im Cache gespeichert werden, um wiederholte get- oder list-Aufrufe für unveränderte Daten zu vermeiden.
  • Erweiterte Konten und Unterkonten:Wenn Sie ein erweitertes Konto haben, authentifizieren Sie sich auf Ebene des erweiterten Kontos, wenn Anrufe auf den gemeinsamen Pool des erweiterten Kontos angerechnet werden sollen.
  • listSubaccounts verwenden:Bei erweiterten Konten verwenden Sie accounts.listSubaccounts anstelle von accounts.list. Das accounts.list-Kontingent wird dem aufrufenden Nutzer (nicht der MC-ID) in Rechnung gestellt und ist in der Standarddiagnose nicht sichtbar. listSubaccounts wird auf Ihr MCA-Kontingent angerechnet.
Zurück
Overview
Weiter
Merchant Center limits