Objekte ändern

**Ziel** :Verstehen, wie Objekte mit der Google Ads API geändert werden.

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

In diesem Leitfaden wird CampaignService verwendet, um das Ändern von Campaign-Objekten zu veranschaulichen. Die gleichen Konzepte gelten jedoch für alle anderen dienstspezifischen Dienste.

Wichtiger Begriff: Eine Ressource der obersten Ebene ist eine Ressource, deren Name keinen Punkt (.) enthält. Campaign ist beispielsweise eine Ressource der obersten Ebene, Campaign.NetworkSettings jedoch nicht.

Mutationsanfragen

Jeder dienstspezifische Dienst hat eine mutate-Methode, die eine Änderungsanfrage akzeptiert. Diese Anfrage besteht aus:

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

Die Methode MutateCampaigns von CampaignService akzeptiert beispielsweise eine MutateCampaignsRequest, die aus Folgendem besteht:

• Einer customer_id
• Einer Sammlung von CampaignOperation-Objekten (operations)
• Optionalen Ausführungseinstellungen (partial_failure, validate_only und response_content_type, die den bevorzugten Antworttyp angeben)

Hinweis: Verfügbare Dienste und Methoden können sich je nach API-Version unterscheiden. Wenn Sie beispielsweise Ziele für den Kunden- und Kampagnenlebenszyklus konfigurieren möchten, verwenden Sie die Mutate* Methoden für GoalService und CampaignGoalConfigService in Version 25 und höher oder die Configure* Methoden für CustomerLifecycleGoalService und CampaignLifecycleGoalService in Version 24 und früher.

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, damit sie den Attributen der update-Ressource entspricht. Wenn dieses Feld festgelegt ist, müssen Sie auch die update_mask des Vorgangs festlegen, die der Google Ads API mitteilt, welche Attribute während des Aktualisierungsvorgangs geändert werden sollen. Jede Clientbibliothek enthält ein Feldmasken-Utility oder eine Hilfs methode, mit der die update_mask für Sie generiert wird.

remove

Entfernt die Ressource, die durch die String-Ressourcennamen angegeben wird (z. B. customers/1234567890/campaigns/987654321).

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

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 kombinieren, anstatt mehrere Mutationsanfragen zu senden, die jeweils einen einzelnen Vorgang enthalten.

Wenn Sie beispielsweise zehn Kampagnen erstellen möchten, sollten Sie eine einzige 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 ändern Sie Ressourcen.

Änderungsantworten

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

Änderungsfehler

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 Änderungsanfragen, die Teilausfälle unterstützen (mit einem Feld partial_failure in der Anfragenachricht), werden bei der Einstellung 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 zur Fehlerbehebung 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 enthält eine Zusammenfassung der Ressourcen, die sich innerhalb eines bestimmten Zeitraums 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 die GoogleAdsService.SearchStream oder GoogleAdsService.Search Methode, um diese Ressourcen abzufragen. Weitere Informationen zum Streamen von Berichten mit GoogleAdsService