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(odercustomerIdin REST-URLs) - Eine Sammlung von
operations - Optionale Ausführungseinstellungen wie
partial_failure,validate_onlyundresponse_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
CampaignOperationObjekten (operations) - Optionale Ausführungseinstellungen (
partial_failure,validate_onlyundresponse_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
updateentspricht. Wenn dieses Feld festgelegt ist, müssen Sie auch dasupdate_maskdes 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 dieupdate_maskfü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_statusbietet eine Zusammenfassung der Ressourcen, die sich innerhalb eines bestimmten Zeitraums geändert haben.change_eventbietet 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