Objekte ändern

Wie im Leitfaden zur API-Struktur beschrieben, hat jede Ressource der obersten Ebene in der Google Ads API einen entsprechenden dienstspezifischen Ressourcentyp, der das Ändern von Instanzen der Ressource unterstützt. Sie können auch GoogleAdsService.Mutate verwenden, um mehrere Ressourcentypen in einer einzelnen Anfrage atomar zu ändern.

In dieser Anleitung wird CampaignService verwendet, um die Änderung von Campaign-Objekten zu demonstrieren. Die gleichen Konzepte gelten jedoch für alle anderen ressourcentypspezifischen Dienste.

Mutationsanfragen

Jeder dienstspezifische Dienst für Ressourcentypen hat eine mutate-Methode, die eine Mutate-Anfrage 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 (die festlegen, ob die veränderliche Ressource oder nur der Ressourcenname nach der Änderung zurückgegeben wird)

Die Methode MutateCampaigns von CampaignService akzeptiert beispielsweise 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 geben den bevorzugten Antworttyp an)

Vorgänge

Mit einem Vorgangsobjekt wie CampaignOperation können Sie die Aktion angeben, die für eine einzelne Ressource ausgeführt werden soll, indem Sie das Feld operation festlegen. Dieses Feld ist ein oneof-Feld mit den folgenden Attributen:

create

Erstellt eine neue Instanz der Ressource.

update

Aktualisiert die Ressource, sodass sie den Attributen der update-Ressource 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 Dienstprogramm für Feldmasken oder eine Hilfsmethode, mit der die update_mask für Sie generiert wird.

remove

Entfernt die Ressource, die durch den String des Ressourcennamens angegeben wird (z. B. customers/1234567890/campaigns/987654321).

Da das Feld operation ein oneof-Feld ist, können Sie nicht mit einem einzigen Vorgang mehrere Objekte ä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

Ein einzelner Vorgang kann nur eine einzelne Ressource erstellen, aktualisieren oder entfernen. Eine einzelne Mutationsanfrage kann jedoch mehrere Vorgänge enthalten. Sie sollten Ihre Vorgänge in einer einzigen Mutationsanfrage kombinieren, anstatt mehrere Mutationsanfragen zu senden, die jeweils einen einzelnen Vorgang enthalten.

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 veränderbaren Felder der Kampagne in campaign. Standardmäßig (RESOURCE_NAME_ONLY) wird nur resource_name in jedem MutateCampaignResult 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 Mutate-Anfragen, die Teilausfälle unterstützen (Anfragen mit dem Feld partial_failure in der Anfragenachricht), werden durch das Festlegen von partial_failure = true gültige Vorgänge übernommen, während bei fehlgeschlagenen Vorgängen vorgangsspezifische Fehler im Feld partial_failure_error der Antwort zurückgegeben werden. Weitere Informationen zum Beheben von Fehlern finden Sie im Leitfaden zu Teilausfällen 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 in einem bestimmten Zeitraum geändert haben.
• change_event enthält 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 Streamen von Berichten mit GoogleAdsService