Objekte ändern

Wie im Leitfaden zur API-Struktur beschrieben, gibt es für jede Ressource auf oberster Ebene in der Google Ads API einen entsprechenden Ressourcentyp-spezifischen Dienst, der das Ändern von Instanzen der Ressource unterstützt. Sie können auch GoogleAdsService.Mutate verwenden, um mehrere Ressourcentypen atomar in einer einzigen Anfrage zu ändern.

In diesem Leitfaden wird CampaignService verwendet, um das Ändern von Campaign-Objekten zu demonstrieren. Dieselben Konzepte gelten jedoch auch für alle anderen ressourcentypspezifischen Dienste.

Mutationsanfragen

Jeder ressourcentypspezifische Dienst hat eine mutate-Methode, die eine Mutationsanfrage akzeptiert. Diese Anfrage besteht aus:

  • Ein customer_id (oder customerId in REST-URLs)
  • Eine Sammlung von operations
  • Optionale Ausführungseinstellungen wie partial_failure, validate_only und response_content_type (bestimmt, ob die änderbare Ressource oder nur der Ressourcenname nach der Änderung zurückgegeben wird)

Beispielsweise akzeptiert die Methode MutateCampaigns von CampaignService ein MutateCampaignsRequest, das aus Folgendem besteht:

  • Ein customer_id
  • Eine Sammlung von CampaignOperation Objekten (operations)
  • Optionale Ausführungseinstellungen (partial_failure, validate_only und response_content_type, die den bevorzugten Antworttyp angeben)

Vorgänge

Mit einem Vorgangsobjekt wie CampaignOperation können Sie die Aktion angeben, die Sie für eine einzelne Ressource ausführen möchten, indem Sie das Feld operation festlegen. Dieses Feld ist ein oneof-Feld, das aus den folgenden Attributen besteht:

create
Erstellt eine neue Instanz der Ressource.
update
Aktualisiert die Ressource, sodass sie den Attributen der Ressource update entspricht. Wenn dieses Feld festgelegt ist, müssen Sie auch das update_mask des Vorgangs festlegen. Dadurch wird der Google Ads API mitgeteilt, welche Attribute während des Aktualisierungsvorgangs geändert werden sollen. Jede Clientbibliothek enthält ein Feldmasken-Dienstprogramm oder eine Hilfsmethode, die die update_mask für Sie generiert.
remove
Entfernt die Ressource, die durch ihren Ressourcennamenstring angegeben wird (z. B. customers/1234567890/campaigns/987654321).

Da das Feld operation ein oneof-Feld ist, können Sie nicht mehrere Objekte mit einem einzigen Vorgang ändern. Wenn Sie beispielsweise eine Kampagne erstellen und eine andere entfernen möchten, fügen Sie Ihrer Anfrage zwei Instanzen von CampaignOperation hinzu: eine mit create und eine mit remove.

Batchvorgänge

Mit einem einzelnen Vorgang kann nur eine einzelne Ressource erstellt, aktualisiert oder entfernt werden. Eine einzelne Mutationsanfrage kann jedoch mehrere Vorgänge enthalten. Sie sollten Ihre Vorgänge in einer einzigen Mutationsanfrage zusammenfassen, anstatt mehrere Mutationsanfragen mit jeweils einem einzelnen Vorgang zu senden.

Wenn Sie beispielsweise zehn Kampagnen erstellen möchten, sollten Sie eine einzelne MutateCampaignsRequest mit zehn CampaignOperation-Objekten senden. Wenn Sie Vorgänge für verschiedene Ressourcentypen in einer einzigen Anfrage gruppieren möchten, verwenden Sie GoogleAdsService.Mutate oder mutating resources.

Antworten ändern

Was in der Antwort zurückgegeben wird, hängt davon ab, was im Feld response_content_type der Mutationsanfrage gesendet wurde. Wenn beispielsweise MUTABLE_RESOURCE angegeben ist, enthält die Antwort sowohl die resource_name der Ressource als auch die änderbaren Felder der Kampagne in campaign. Standardmäßig (RESOURCE_NAME_ONLY) wird in jedem MutateCampaignResult nur die resource_name ausgefüllt.

Mutationsfehler

Standardmäßig (partial_failure = false) werden die Vorgänge in einer Mutationsanfrage nur dann auf Ihr Google Ads-Konto angewendet, wenn jeder Vorgang in der Anfrage erfolgreich ist. Wenn ein Vorgang fehlschlägt, wird die gesamte Anfrage zurückgesetzt. Bei Mutationsanfragen, die Teilfehler unterstützen (Anfragen mit einem partial_failure-Feld in der Anfragenachricht), werden durch Festlegen von partial_failure = true gültige Vorgänge übernommen, während fehlgeschlagene Vorgänge im Feld partial_failure_error der Antwort vorgangsspezifische Fehler zurückgeben. Weitere Informationen zur Fehlerbehebung finden Sie im Leitfaden zu Teilfehlern und im Leitfaden zu häufigen Fehlern.

Änderungen nachverfolgen

Wenn Sie Änderungen an Objekten in Ihrem Google Ads-Konto nachverfolgen oder den aktuellen Status von Objekten abrufen möchten, können Sie die Ressourcen change_status und change_event verwenden.

  • change_status bietet eine Zusammenfassung der Ressourcen, die sich innerhalb eines bestimmten Zeitraums geändert haben.
  • change_event bietet einen detaillierten Verlauf der Änderungen, einschließlich der alten und neuen Werte der geänderten Felder.

Verwenden Sie zum Abfragen dieser Ressourcen die Methode GoogleAdsService.SearchStream oder GoogleAdsService.Search. Weitere Informationen zum Berichts-Streaming mit GoogleAdsService