Ressourcen mutieren

Die Google Ads API bietet je nach Anwendungsfall mehrere Möglichkeiten, Ressourcen zu ändern:

• Änderungen am Ressourcendienst: Jede änderbare Ressource hat einen dedizierten Dienst, der Vorgänge für diesen bestimmten Ressourcentyp ausführt. Die Ressource Campaign verwendet beispielsweise den Endpunkt CampaignService.MutateCampaigns, um Kampagnen zu erstellen, zu aktualisieren oder zu entfernen.
• Bulk-Mutates: Der Endpunkt GoogleAdsService.Mutate fasst eine Sequenz von Mutate-Vorgängen für mehrere Ressourcentypen (und unterstützte Aktionsvorgänge wie das Buchen oder Erstellen von Angeboten für Kampagnen) in einer einzigen synchronen Anfrage zusammen.
• Asynchrone Batchjobs: Für umfangreiche Mutationen oder lang laufende Arbeitslasten führt BatchJobService Vorgänge asynchron aus, ohne dass Zeitüberschreitungen bei synchronen Anfragen auftreten. Im Gegensatz zu GoogleAdsService.Mutate wird BatchJobService immer mit Semantik für Teilausfälle ausgeführt und unterstützt weder den validate_only-Modus noch Aktionsvorgänge (book_campaigns_operation, quote_campaigns_operation). Da Teilausfälle immer aktiv sind, lehnt BatchJobService Ressourcenvorgänge, deren zugrunde liegende Dienste keine Teilausfälle unterstützen (z. B. CustomerOperation, CampaignConversionGoalOperation, ConversionGoalCampaignConfigOperation, CustomConversionGoalOperation und CustomerConversionGoalOperation), mit MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE ab.

Vorteile von Bulk-Mutates

Die Verwendung von GoogleAdsService.Mutate bietet die folgenden Vorteile (siehe Best Practices für Mutate für Implementierungshinweise):

• Gruppierte Aktionen für verschiedene Ressourcendienste: Während einzelne Ressourcendienstaufrufe nur Vorgänge für einen einzelnen Ressourcentyp akzeptieren, können Sie mit GoogleAdsService.Mutate mehrere Ressourcentypen in einem Aufruf ändern.
• Temporäre Ressourcennamen: Sie können neu erstellten übergeordneten Entitäten negative Ganzzahl-IDs (z. B. customers/CUSTOMER_ID/campaigns/-1) zuweisen und diese temporären IDs in untergeordneten Vorgängen innerhalb derselben Anfrage referenzieren.

Mit diesen Funktionen können Sie mit GoogleAdsService.Mutate eine gesamte Kampagnenhierarchie unteilbar erstellen, sodass alle Vorgänge entweder erfolgreich sind oder fehlschlagen. Alternativ können Sie partial_failure auf true festlegen, um gültige Vorgänge unabhängig voneinander zu bestätigen.

Wichtiger Hinweis: Jede Mutationsanfrage bezieht sich auf ein einzelnes customer_id. Daher können mit einem einzelnen Aufruf nicht gleichzeitig Ressourcen in mehreren Kundenkonten geändert werden. Darüber hinaus kann ein Konto keine Objekte ändern, die von einem anderen Konto erstellt wurden, es sei denn, es authentifiziert sich als autorisiertes Verwaltungskonto mit dem konfigurierten Header login-customer-id.