Mutationen des Ressourcendienstes

Die Verwendung des dedizierten Dienstes einer Ressource ist die direkteste Methode, um Entitäten eines einzelnen Ressourcentyps in der Google Ads API zu erstellen, zu aktualisieren oder zu entfernen.

Mutate-Endpunkte

Jede veränderliche Ressource hat einen entsprechenden Dienst- und Vorgangstyp. Wenn Sie eine Ressource mit dem zugehörigen Dienst ändern möchten, füllen Sie eines der folgenden Felder im Vorgang aus und senden Sie es an den Mutate-Endpunkt des Dienstes:

  • Erstellen (create): Ein neues Ressourcenobjekt, das erstellt werden soll.
  • Aktualisieren (update): Das geänderte Ressourcenobjekt, begleitet von einem update_mask, das die geänderten Felder angibt.
  • Entfernen (remove): Der resource_name-String der Zielressource, der entfernt werden soll.

So erstellen Sie beispielsweise eine neue Campaign:

  1. Erstellen Sie ein Campaign-Objekt mit den gewünschten Attributen.
  2. Weisen Sie sie dem Feld create einer CampaignOperation zu.
  3. Senden Sie den Vorgang in einem MutateCampaignsRequest an CampaignService.MutateCampaigns.

Dieses Muster gilt für alle ressourcenspezifischen Dienste in der Google Ads API:

Die folgende REST-JSON-Nutzlast veranschaulicht eine Anfrage an CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Mehrere Vorgänge und Einschränkungen

Da das Feld operations einer Mutationsanfrage wiederholt wird, kann eine einzelne Anfrage mehrere Vorgänge (bis zu 10.000 Vorgänge pro Anfrage) für diesen Ressourcentyp enthalten. Standardmäßig werden alle Vorgänge in der Anfrage atomar ausgeführt, sofern Sie partial_failure nicht auf true festlegen.

Für einzelne Ressourcendienste gelten jedoch zwei wichtige Einschränkungen:

  • Einzelner Ressourcentyp:Bei einer Anfrage an einen Ressourcendienst können nur Ressourcen geändert werden, die von diesem Dienst verwaltet werden.
  • Keine temporären Ressourcen-IDs oder Querverweise:Vorgänge in einem ressourcenspezifischen Mutate-Aufruf werden unabhängig voneinander verarbeitet. Sie können keine temporären negativen IDs (z. B. customers/CUSTOMER_ID/campaigns/-1) zuweisen oder in derselben Anfrage in anderen Vorgängen auf neu erstellte Elemente verweisen.

Wenn Sie mehrere Ressourcentypen in einer einzelnen Anfrage ändern oder in abhängigen Vorgängen auf temporäre Ressourcennamen verweisen müssen, verwenden Sie stattdessen GoogleAdsService.Mutate.

Versionsspezifische Unterschiede

Beachten Sie beim Ändern von Ressourcen die folgenden Unterschiede zwischen den unterstützten Google Ads API-Versionen:

  • Dienste für Zielvorhaben für den Kundenlebenszyklus:In Version 25 und höher werden alle Zielvorhaben für den Kundenlebenszyklus, einschließlich „Kundenakquisition“ (new_customer_acquisition_goal_settings), „Kundenbindung“ (retention_goal_settings) und „Kundenbindung durch Treuepunkte“ (loyalty_retention_goal_settings), über GoalService.MutateGoals und CampaignGoalConfigService.MutateCampaignGoalConfigs mit einem standardmäßigen wiederholten operations-Feld geändert. Dadurch werden CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals und CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals ersetzt, die in Version 24 und früher für die Kundenakquisition verwendet werden und ein einzelnes operation-Feld akzeptieren.
  • Datums- und Zeitfelder für Kampagnen:Beim Erstellen oder Aktualisieren einer Campaign werden in Version 23 und höher start_date_time und end_date_time (yyyy-MM-dd HH:mm:ss) verwendet. Diese ersetzen die Felder start_date und end_date, die in Version 22 nur das Datum enthalten.
  • Änderbarkeit der Attestierung synthetischer Inhalte:Obwohl Asset.synthetic_content_info und Ad.synthetic_content_info im Schema für Version 22 und höher enthalten sind, können die Felder synthetic_content_info.advertiser_attestation.status und synthetic_content_info.advertiser_attestation.source nur in Version 23 und höher geändert werden (system_attestation ist immer OUTPUT_ONLY). Wenn Sie versuchen, advertiser_attestation-Unterfelder in Version 22 zu ändern, wird ein Fehler vom Typ „immutable-field“ ("The field attempted to be mutated is immutable" oder "Field cannot be set") zurückgegeben.
Zurück
Übersicht
Weiter
Bulk-Mutations