Mutationen des Ressourcendienstes

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

Mutate-Endpunkte

Jede änderbare Ressource hat einen entsprechenden Dienst- und Vorgangstyp. Wenn Sie eine Ressource über den 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, zusammen mit einer update_mask, die die geänderten Felder angibt.
• Entfernen (remove): Der resource_name-String der zu entfernenden Zielressource.

So erstellen Sie beispielsweise einen neuen 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 einer MutateCampaignsRequest an CampaignService.MutateCampaigns.

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

• AdGroup: Übergeben Sie einen AdGroupOperation an AdGroupService.MutateAdGroups.
• CampaignCriterion: Übergeben Sie einen CampaignCriterionOperation an CampaignCriterionService.MutateCampaignCriteria.

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

Die meisten ressourcenspezifischen Mutationsanfragen akzeptieren ein wiederkehrendes operations-Feld. Eine einzelne Anfrage kann also mehrere Vorgänge für diesen Ressourcentyp enthalten (bis zu 10.000 Vorgänge pro Anfrage oder 20.000 für AdGroupCriterionService.MutateAdGroupCriteria; CustomerService.MutateCustomer akzeptiert ein einzelnes operation-Feld). Standardmäßig werden alle Vorgänge in der Anfrage atomar ausgeführt, es sei denn, der Dienst unterstützt partial_failure und Sie legen den Wert auf true fest.

Einzelne Ressourcendienste haben jedoch zwei wichtige Einschränkungen:

• Einzelner Ressourcentyp: Eine Anfrage an einen Ressourcendienst kann nur Ressourcen ändern, die von diesem bestimmten Dienst verwaltet werden.
• Keine ressourcenübergreifenden temporären IDs: Da ein ressourcenspezifischer Änderungsaufruf nur einen einzigen Ressourcentyp akzeptiert, können Sie einer übergeordneten Ressource (z. B. customers/CUSTOMER_ID/campaigns/-1) keine temporäre negative ID zuweisen und sie in derselben Anfrage von einer untergeordneten Ressource eines anderen Typs (z. B. AdGroup) referenzieren. (Selbstreferenzierende temporäre IDs innerhalb desselben Ressourcentyps werden für hierarchische Bäume wie AdGroupCriterion-Eintragsgruppen und AssetGroupListingGroupFilter-Knoten unterstützt.)

Wenn Sie mehrere Ressourcentypen in einer einzelnen Anfrage ändern oder temporäre Ressourcennamen über verschiedene Ressourcentypen hinweg referenzieren müssen, verwenden Sie stattdessen GoogleAdsService.Mutate.

Versionsspezifische Unterschiede

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

• Dienste für Zielvorhaben für den Kundenlebenszyklus: Zielvorhaben „Kundenbindung“ werden in allen unterstützten Versionen über GoalService.MutateGoals (retention_goal_settings) und CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) mit einem standardmäßigen wiederkehrenden operations-Feld geändert. In v25 und höher werden die Kundenakquisition (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) und die Kundenbindung (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) ebenfalls über GoalService.MutateGoals und CampaignGoalConfigService.MutateCampaignGoalConfigs geändert. Diese ersetzen CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals und CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, die in v23 und v24 für die Kundenakquisition verwendet werden und ein einzelnes operation-Feld akzeptieren.