Best Practices und Einschränkungen

Beachten Sie bei der Verwendung von BatchJobService die folgenden Richtlinien.

Durchsatz verbessern

  • Wenige größere Jobs sind vielen kleineren Jobs vorzuziehen.

  • Sortieren Sie hochgeladene Vorgänge nach Vorgangstyp (mit Ausnahme von voneinander abhängigen Vorgängen, die nacheinander in atomaren Unterbatches gruppiert werden müssen). Wenn Ihr Job beispielsweise Vorgänge zum Hinzufügen von Standardkampagnen, Anzeigengruppen und Anzeigengruppenkriterien enthält, ordnen Sie die Vorgänge in Ihrem Upload so, dass alle Kampagnenvorgänge zuerst aufgeführt werden, gefolgt von allen Anzeigengruppenvorgängen und schließlich allen Anzeigengruppenkriterienvorgängen.

  • Bei Vorgängen desselben Typs kann die Leistung verbessert werden, wenn sie nach übergeordneter Ressource gruppiert werden. Wenn Sie beispielsweise eine Reihe von AdGroupCriterionOperation-Objekten haben, ist es effizienter, Vorgänge nach Anzeigengruppe zu gruppieren, anstatt Vorgänge zu mischen, die sich auf Kriterien in verschiedenen Anzeigengruppen auswirken.

Atomarität bei der Batchaufteilung

Die Google Ads API teilt die Vorgänge in einem eingereichten Batchjob zur Verarbeitung in kleinere Unterbatches auf. Während Standard-Unterbatches mit aktiviertem Teilfehler ausgeführt werden, werden Unterbatches für bestimmte voneinander abhängige Vorgänge atomar als einzelne Transaktion verarbeitet:

Für die Erstellung von Unterbatches für AssetGroup und Performance Max-Kampagnen (Campaign) gilt Folgendes: Es sind insgesamt bis zu 1.000 Vorgänge pro Unterbatch zulässig. Alle untergeordneten create-Vorgänge über 999 werden in den nächsten nicht atomaren Unterbatch verschoben.

  • Der übergeordnete create-Vorgang (resource_name für AssetGroup oder Campaign) und die nachfolgenden untergeordneten create-Vorgänge (asset_group für AssetGroupAsset oder campaign für CampaignAsset) müssen dieselbe negative temporäre ID angeben.
  • Platzieren Sie alle erforderlichen AssetOperation-Vorgänge (create) für neue Asset-Ressourcen vor dem übergeordneten AssetGroupOperation oder CampaignOperation (create), niemals zwischen dem übergeordneten create und seinen untergeordneten Link-create-Vorgängen (wodurch der atomare Sub-Batch sofort geschlossen und die Erstellung der übergeordneten Ressource von ihren verknüpften Assets getrennt würde).

Wenn ein atomarer Unterbatch fehlschlägt, enthält der BatchJobResult.status des fehlerhaften Vorgangs den zugrunde liegenden Validierungsfehler. Die verbleibenden Vorgänge in diesem Unterbatch werden mit dem entsprechenden Transaktionsfehler für diesen Unterbatch zurückgesetzt. Prüfen Sie die benachbarten BatchJobResult-Einträge mit derselben AdGroup-, AssetGroup- oder Campaign-ID, um die Fehlerursache zu ermitteln.

Wenn zusammengehörige Vorgänge in einer dieser Gruppen nicht nacheinander hinzugefügt werden, werden sie von der Google Ads API auf separate Unterbatches aufgeteilt. Das führt dazu, dass die Änderung die Mindestanforderungen für Assets nicht erfüllt oder die Eintragsgruppenbäume unvollständig bleiben. Weitere Informationen finden Sie unter Filter für Eintragsgruppen in Batchjobs verwenden und Batchverarbeitung für Performance Max-Kampagnen.

Logische Gruppierung

Wenn Sie eine Produktausrichtungshierarchie (AssetGroupListingGroupFilterOperation in Performance Max-Kampagnen oder AdGroupCriterionOperation in Shopping-Kampagnen) ändern oder eine neue AssetGroup oder Performance Max-Campaign erstellen, gruppieren Sie alle Vorgänge, die auf dieselbe übergeordnete Ressource (AssetGroup, AdGroup oder Campaign) ausgerichtet sind, nacheinander. Dadurch werden Sperrkonflikte im Backend reduziert und voneinander abhängige Bäume bleiben zusammen.

Datenkonsistenz

Da Filterbäume für Eintragsgruppen und Asset-Anforderungen für Performance Max-Kampagnen am Ende jeder atomaren Unterbatch-Transaktion validiert werden, sollten Sie Aktualisierungen derselben übergeordneten Ressource nicht auf nicht zusammenhängende Bereiche in einem Job oder auf gleichzeitige Jobs aufteilen.

Nebenläufigkeitsprobleme vermeiden

  • Wenn Sie mehrere gleichzeitige Jobs für dasselbe Konto senden, sollten Sie die Wahrscheinlichkeit verringern, dass Jobs gleichzeitig für dieselben Objekte ausgeführt werden, und gleichzeitig große Jobgrößen beibehalten. Viele unvollständige Jobs mit dem Status RUNNING, die versuchen, dieselbe Gruppe von Objekten zu mutieren, können zu Deadlock-ähnlichen Bedingungen führen, was zu einer erheblichen Verlangsamung und sogar zu Jobfehlern führt.

  • Senden Sie nicht mehrere Vorgänge, die dasselbe Objekt im selben Job ändern, da das Ergebnis unvorhersehbar sein kann.

Ergebnisse optimal abrufen

  • Fragen Sie den Jobstatus nicht zu häufig ab, da sonst Fehler aufgrund von Ratenbegrenzungen auftreten können.

  • Lassen Sie page_size beim Aufruf von ListBatchJobResults ungesetzt (oder setzen Sie es auf den Höchstwert von 1000), um die Anzahl der Seitenwechsel zu minimieren. Setzen Sie response_content_type nur dann auf MUTABLE_RESOURCE, wenn Ihre Anwendung die zurückgegebenen Ressourcenfelder über resource_name hinaus prüft.

  • Die Reihenfolge der Ergebnisse entspricht der Reihenfolge des Uploads.

Zusätzliche Nutzungshinweise

  • Sie können eine Obergrenze für die Ausführungsdauer eines Batchjobs festlegen, bevor er abgebrochen wird. Legen Sie beim Erstellen eines neuen Batchjobs im Feld metadata.execution_limit_seconds das gewünschte Zeitlimit in Sekunden fest. Wenn metadata.execution_limit_seconds nicht festgelegt ist, gibt es kein Standardzeitlimit.

  • Obwohl das Protokolllimit bei 10.000 Vorgängen pro Anfrage liegt, empfehlen wir, nicht mehr als 1.000 Vorgänge pro AddBatchJobOperationsRequest hinzuzufügen und die restlichen Vorgänge mit der sequence_token in denselben Job hochzuladen. Je nach Größe der Vorgänge kann das Senden zu vieler Vorgänge in einer einzelnen AddBatchJobOperationsRequest zu einem BatchJobError.REQUEST_TOO_LARGE-Fehler führen. Sie können diesen Fehler beheben, indem Sie die Anzahl der Vorgänge reduzieren und den AddBatchJobOperationsRequest wiederholen.

Beschränkungen

  • Jeder BatchJob unterstützt bis zu eine Million Vorgänge. Wenn Sie dieses Limit beim Aufrufen von AddBatchJobOperations überschreiten, wird ein ResourceCountLimitExceededError.RESOURCE_LIMIT-Fehler zurückgegeben (mit ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB in ErrorDetails.resource_count_details).

  • Pro Konto können bis zu 100 aktive oder ausstehende Jobs gleichzeitig vorhanden sein. Wenn Sie dieses Limit beim Erstellen eines Batchjobs mit MutateBatchJob überschreiten, wird der Fehler ResourceCountLimitExceededError.RESOURCE_LIMIT (mit ResourceLimitType.BATCH_JOBS_PER_CUSTOMER in ErrorDetails.resource_count_details) zurückgegeben.

  • Ausstehende Jobs, die älter als 7 Tage sind, werden automatisch entfernt.

  • Für jede AddBatchJobOperationsRequest gilt ein festes Limit von 10.000 Mutationsvorgängen pro Anfrage. Wenn Sie mehr als 10.000 Vorgänge in einer einzelnen Anfrage ausführen,wird der Fehler BatchJobError.REQUEST_TOO_LARGE zurückgegeben.

  • Für das Feld page_size in ListBatchJobResultsRequest:

  • Jeder AddBatchJobOperationsRequest hat eine maximale Größe von 41.937.920 Byte. Wenn Sie dieses Limit überschreiten, erhalten Sie den Fehler BatchJobError.REQUEST_TOO_LARGE (oder INTERNAL_ERROR, wenn die Anfrage auf der Transportschicht abgelehnt wird). Sie können die serialisierte Größe der Anfrage vor dem Senden ermitteln und entsprechende Maßnahmen ergreifen, wenn sie zu groß ist:

    Java

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    C#

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Ruby

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    Perl

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

Größe eines einzelnen Änderungsvorgangs

Die Gesamtgröße der Anfrage kann bis zu 41.937.920 Byte betragen, die serialisierte Größe einer einzelnen MutateOperation im Batch ist jedoch auf 10.484.504 Byte (10 MiB minus 1.256 Byte) begrenzt. Bei Überschreiten dieses Limits wird ein BatchJobError.REQUEST_TOO_LARGE-Fehler zurückgegeben. In der Referenzdokumentation für BatchJobError.REQUEST_TOO_LARGE wird zwar der Schwellenwert von 10.484.504 Byte genannt, AddBatchJobOperations gibt jedoch denselben Fehlercode zurück, wenn einer der drei Anfrage-Schwellenwerte (41.937.920 Byte insgesamt, 10.484.504 Byte für einen einzelnen Vorgang oder 10.000 Vorgänge pro Aufruf) überschritten wird. Im Feld message des Fehlers wird angegeben, welches Limit überschritten wurde.

Zurück
Filter für Eintragsgruppen