Best Practices und Einschränkungen

Beachten Sie die folgenden Richtlinien, wenn Sie BatchJobService verwenden.

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 Anzeigengruppenkriterien 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 (bis zu 1.000 Vorgänge insgesamt pro Unterbatch; 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. Für die verbleibenden Vorgänge in diesem Unterbatch wird ein Rollback mit dem entsprechenden Transaktionsfehler für diesen Unterbatch durchgeführt. 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 ändern (AssetGroupListingGroupFilterOperation in Performance Max-Kampagnen oder AdGroupCriterionOperation in Shopping-Kampagnen) oder eine neue AssetGroup oder Performance Max-Kampagne Campaign erstellen, gruppieren Sie alle Vorgänge, die auf dieselbe übergeordnete Ressource (AssetGroup, AdGroup oder Campaign) ausgerichtet sind, nacheinander. Dadurch werden Backend-Sperrkonflikte reduziert und voneinander abhängige Bäume zusammengehalten.

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 einreichen, sollten Sie die Wahrscheinlichkeit verringern, dass Jobs gleichzeitig auf dieselben Objekte zugreifen, während die Jobgrößen groß bleiben. 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 ungesetzt (oder setzen Sie es auf den Höchstwert von 1000), wenn Sie ListBatchJobResults aufrufen, 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 der Uploads.

Zusätzliche Nutzungshinweise

  • Sie können eine ungefähre Obergrenze dafür festlegen, wie lange ein Batchjob ausgeführt werden darf, bevor er abgebrochen wird. Wenn Sie einen neuen Batchjob erstellen, legen Sie für das Feld metadata.execution_limit_seconds eine positive Ganzzahl für 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).

  • Jedes Konto kann bis zu 100 aktive oder ausstehende Jobs gleichzeitig haben. Wenn Sie dieses Limit beim Erstellen eines Batchjobs mit MutateBatchJob überschreiten, wird ein ResourceCountLimitExceededError.RESOURCE_LIMIT-Fehler zurückgegeben (mit ResourceLimitType.BATCH_JOBS_PER_CUSTOMER in ErrorDetails.resource_count_details).

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

  • Für jede AddBatchJobOperationsRequest gilt ein festes Limit von 10.000 Änderungsvorgä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)

# Supports both proto-plus (use_proto_plus=True) and native protobuf
# (use_proto_plus=False) messages.
pb = type(request).pb(request) if hasattr(type(request), "pb") else request
size_in_bytes = pb.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 Gesamtanfrage kann bis zu 41.937.920 Byte groß sein, die serialisierte Größe eines einzelnen MutateOperation innerhalb des Batches 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 pro 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