Kontingente

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

Die Merchant API verwendet Kontingente, um eine stabile und faire Umgebung für alle Nutzer zu gewährleisten. 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. So hat die Methode zum Auflisten von Datenquellen für Einträge accounts.dataSources.list eine eigene Kontingentgruppe.
  • Mehrere Methoden pro Gruppe (Bündelung) : Oft werden verwandte Methoden zu einer einzigen Kontingentgruppe zusammengefasst. Für alle Methoden in dieser Gruppe gelten dieselben Tages- und Minutengrenzwerte. Häufige Beispiele:
    • Alle Lesevorgänge für verwandte Methoden und Ressourcen gruppieren, z. B. merchant-accounts-read-methods.
    • Alle Schreibvorgänge für verwandte Methoden und Ressourcen gruppieren, z. B. merchant-accounts-write-methods.

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

Die integrierte HTTP-Batchverarbeitung 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 berechnet.

Ausnahme für die Batchverarbeitung in bestimmten Regionen: Spezialisierte Methoden für die Batchverarbeitung in bestimmten Regionen (batchCreate, batchUpdate, batchDelete) werden als ein einziger API-Aufruf auf die merchant_regions Kontingentgruppe angerechnet, unabhängig von der Anzahl der Regionsvorgänge in der Nutzlast.

Um Ihre Integration effektiv zu verwalten, sollten Sie die spezifische Kontingentgruppe für jede API-Methode prüfen, die Sie verwenden möchten. Diese Details finden Sie in der Methode zum Auflisten von Kontingenten. Weitere Informationen finden Sie unter Monitoring und Sichtbarkeit.

Richtlinie aktualisieren

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

  • Standardmäßig können Sie Ihre Produkte bis zu zweimal pro Tag aktualisieren. Sie sollten die Aufrufe gleichmäßig über den Tag verteilen, um das Kontingent pro Minute einzuhalten.
  • Standardmäßig können Sie Ihre Unterkonten nur bis zu zweimal pro Tag aktualisieren. Ihr tägliches Kontingent für Unterkonto-Updates ist ein aggregiertes Limit, das auf der Gesamtzahl der zulässigen Unterkonten basiert.
  • Standardmäßig können Sie Methoden für Datenquellen für Ihre Unterkonten wie list oder create nur bis zu zweimal pro Unterkonto und Tag aufrufen.

Ratenkontingente

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

  • Tageslimit (quotaLimit) : Die maximale Anzahl der Anfragen, die pro Tag zulässig sind. Die täglichen Kontingentlimits werden um 12:00 Uhr UTC zurückgesetzt.
  • Limit pro Minute (quotaMinuteLimit) : Die maximale Anzahl der Anfragen, die pro Minute zulässig sind. Damit wird die Anfragerate gesteuert. Für die Kontingentlimits pro Minute wird ein gleitendes Zeitfenster verwendet. Der Zeitraum beginnt mit dem ersten API-Aufruf für diese Methode und Ressource. Wenn Sie beispielsweise um 10:01:30 Uhr einen Aufruf ausführen, gilt 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 wurden. 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 quotas.list Methode.

Die spezifischen Tages- und Minutengrenzwerte variieren je nach Kontingentgruppe erheblich. Vorgänge mit einem höheren erwarteten Volumen oder geringeren Systemkosten, z. B. das Lesen von Produktdaten, haben in der Regel höhere Grenzwerte. Umgekehrt können intensivere oder sensiblere Vorgänge wie Kontoänderungen niedrigere Grenzwerte haben.

Kontingentzuweisung und -hierarchie

In diesem Abschnitt wird erläutert, in wessen Namen 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 eigenständiges Konto einen API-Aufruf authentifiziert, wird diese 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 verwendet.
  • Erweiterte Konten: Wenn Sie sich als erweitertes Konto authentifizieren, wird das Kontingent aus dem Pool des erweiterten Kontos verwendet, auch wenn Sie ein Unterkontoverwenden.
    • Beispiel:Eine Agentur Retail Management Account (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 für Bekleidungsgeschäft B (accounts/11111) auf. Das Kontingent wird aus dem Pool der übergeordneten Agentur (erweiterte Konto-ID: 12345) verwendet, nicht aus dem Pool des Unterkontos.
  • Unterkonten:Wenn API-Aufrufe mit den Anmeldedaten eines Unterkontos authentifiziert werden, wird das Kontingent dem individuellen Pool dieses Unterkontos belastet. Dies funktioniert genauso wie bei einem eigenständigen Konto, obwohl es von einem übergeordneten erweiterten Konto verwaltet wird.
    • Beispiel: Wenn Bekleidungsgeschäft B (Konto-ID: 11111) mit derselben Einrichtung wie zuvor Anmeldedaten verwendet, die speziell für das Unterkonto eingerichtet wurden, um products.insert für das eigene Konto (accounts/11111) aufzurufen, wird das Kontingent aus dem individuellen Kontingentpool von Bekleidungsgeschäft B's verwendet. Der Pool der übergeordneten Agentur bleibt unverändert.

Ausnahmen von den allgemeinen Regeln

Es gibt einige spezifische Ausnahmen von den allgemeinen Regeln für die Kontingentzuweisung:

  • Accounts.list: Das Kontingent für diese Methode wird dem authentifizierten Nutzer oder Dienstkonto belastet, das den Aufruf ausführt, nicht der Merchant Center-Konto-ID. Die Kontingentnutzung ist auf der Standardseite für die Merchant Center API-Diagnose nicht sichtbar. Wenn Sie ein erweitertes Konto haben, empfehlen wir die Verwendung der accounts.listSubaccounts Methode, die auf das Kontingent Ihres erweiterten Kontos angerechnet wird.
  • Methoden zur Ausstellerauflösung: 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. Nutzer werden auf die Website des Händlers weitergeleitet, um den Kauf abzuschließen. Bei API-Aufrufen werden Kontingente auf die spezifische 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. Wenn sie sich mit ihren eigenen Anmeldedaten authentifiziert, um diesen API-Aufruf auszuführen, wird das Kontingent direkt aus dem Kontingentpool der Europe Shopping Group verwendet.
    • Eine Preisvergleichsportal-Domain TopDeals CSS (Konto-ID: 20002) authentifiziert sich, 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 von TopDeals CSS verwendet, nicht aus dem Pool des Händlerkontos.

  • Marktplätze:Marktplätze sind Onlineplattformen, auf denen mehrere einzelne Händler vertreten sind. Sie fungieren als spezielle erweiterte Konten, mit denen Sie für jeden Ihrer Verkäufer ein eigenes Unterkonto 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. Sie kann einzelne Preisvergleichsportale, Konten und Unterkonten als unterste Ebene enthalten.

Automatische Kontingentanpassung

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

Die Kontingentgruppen, die in automatische Kontingentanpassungen einbezogen werden, sind:

Produktdienste

  • Alle Kontingentgruppen von Methoden, die sich auf die Ressourcen products und productInputs beziehen.
  • Das tägliche Aufrufkontingent wird in der Regel auf das Doppelte des Angebotskontingents des Händlers festgelegt. Dabei wird davon ausgegangen, dass ein Händler jedes seiner Produkte bis zu zweimal pro Tag 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 Aufrufkontingent wird auf die maximale Anzahl der für dieses Konto zulässigen Unterkonten festgelegt. So sind bis zu zwei Lesevorgänge pro Unterkonto und Tag möglich.

Datenquellendienste

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

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

Was passiert, wenn Kontingente überschritten werden?

Wenn ein Kontingent überschritten wurde, werden in den API-Antworten und auf der Diagnoseseite 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 beziehen sich auf Merchant Center-Limits und nicht auf Merchant API-Kontingente. Sie können versuchen, ein zusätzliches Kontingent an Artikeln, Feeds oder Unterkonten anzufordern:

  • too_many_items: Merchant-Kontingent überschritten
  • too_many_subaccounts: Maximale Anzahl von Unterkonten erreicht

Monitoring und Sichtbarkeit

Wenn Sie die aktuellen Aufrufkontingente 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"
        }
    ]
}

Prozess zur Kontingenterhöhung

Wenn Sie ein zusätzliches Kontingent anfordern möchten, öffnen Sie das Formular Support kontaktieren, wählen Sie im Feld „Problem/Frage“ die Option „Anfrage zur Kontingenterhöhung“ aus und füllen Sie alle Pflichtfelder 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 umsatzstarker Shopping-Saisons anfordern. Permanente Kontingenterhöhungen für diese Arten von Ressourcen sind nicht möglich.
  • Für alle anderen Ressourcen ohne automatische Kontingente:Fordern Sie bei Bedarf Kontingenterhöhungen an.

Wir empfehlen, Ihre Kontingente regelmäßig zu prüfen, um sicherzustellen, dass Sie über ausreichend Kontingent für Ihre Implementierung verfügen, und um zu sehen, wie Ihr Kontingent automatisch angepasst wird. Mit der Methode quotas.list können Sie Ihr aktuelles Tageskontingentlimit, das Limit pro Minute und die aktuelle tägliche Nutzung für jede API-Methodengruppe einsehen.

Best Practices

Wenn Sie diese Best Practices implementieren, können Sie sicherstellen, dass Ihre Integration reibungslos funktioniert, unerwartete Kontingentfehler vermieden werden und Merchant Center-Ressourcen effizient genutzt werden.

Anfragenverteilung 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) einzuhalten.
  • Proaktive Drosselung:Implementieren Sie in Ihrer Anwendung eine clientseitige Ratenbegrenzung (Drosselung). Verlassen Sie sich nicht nur auf die Server von Google, um übermäßigen Traffic abzulehnen. Steuern Sie die Anforderungsrate an der Quelle.

Fehlerbehandlung

  • HTTP 429-Fehler behandeln:Ihre Anwendung muss in der Lage sein, 429-Fehler vom Typ „Too Many Requests“ (quota/request_rate_too_high) zu verarbeiten.
  • Exponentieller Backoff mit Jitter:Wenn Sie fehlgeschlagene Anfragen wiederholen (insbesondere nach einem 429-Fehler), verwenden Sie den exponentiellen Backoff (längere Wartezeiten) und fügen Sie „Jitter“ (zufällige Verzögerung) hinzu. Jitter verhindert „Retry Storms“, bei denen mehrere Clientinstanzen genau gleichzeitig Wiederholungsversuche ausführen und den Server erneut überlasten.
  • Hinweise zu Wiederholungen beachten:Wenn die API-Antwort Details oder Header für Wiederholungen enthält, verwenden Sie diese, um zu bestimmen, wann Sie die Aufrufe fortsetzen können.

Redundante Aufrufe minimieren

  • Veraltete Aufrufe vermeiden (404 NOT_FOUND) : Fordern Sie keine Ressourcen an oder löschen Sie keine Ressourcen, die nicht mehr vorhanden sind. Auch fehlgeschlagene Aufrufe verbrauchen API-Kontingent. Beobachten Sie NOT_FOUND-Fehler in der Merchant Center API-Diagnose, um veraltete Statusverfolgung oder unnötige Abrufe zu erkennen.
  • Vor dem Aktualisieren prüfen:Prüfen Sie vor dem Senden einer Aktualisierungsanfrage, ob sich die Daten tatsächlich geändert haben. Vermeiden Sie es, Updates zu senden, die dieselben Werte schreiben.
  • Caching verwenden:Speichern Sie Lesevorgänge (z.B. Produktdetails, Einstellungen) bei Bedarf lokal, 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 der Ebene des erweiterten Kontos, wenn Aufrufe auf den gemeinsamen Pool des erweiterten Kontos angerechnet werden sollen.
  • Verwenden Sie listSubaccounts: Verwenden Sie für erweiterte Konten accounts.listSubaccounts anstelle von accounts.list. Das Kontingent für accounts.list wird dem aufrufenden Nutzer belastet (nicht der Merchant Center-ID) und ist in der Standarddiagnose nicht sichtbar. listSubaccounts wird auf Ihr MCA-Kontingent angerechnet.
Zurück
Overview
Weiter
Merchant Center limits