Mutazioni del servizio di risorse

L'utilizzo del servizio dedicato di una risorsa è il modo più diretto per creare, aggiornare o rimuovere entità di un singolo tipo di risorsa nell'API Google Ads.

Endpoint di mutazione

Ogni risorsa modificabile ha un tipo di servizio e di operazione corrispondente. Per modificare una risorsa utilizzando il servizio dedicato, compila uno dei seguenti campi dell'operazione e invialo all'endpoint di modifica del servizio:

• Crea (create): un nuovo oggetto risorsa da creare.
• Aggiornamento (update): l'oggetto risorsa modificato, accompagnato da un update_mask che specifica i campi modificati.
• Rimuovi (remove): la stringa resource_name della risorsa di destinazione da rimuovere.

Ad esempio, per creare un nuovo Campaign, completa i seguenti passaggi:

1. Crea un oggetto Campaign con gli attributi che hai scelto.
2. Assegnalo al campo create di un CampaignOperation.
3. Invia l'operazione in un MutateCampaignsRequest a CampaignService.MutateCampaigns.

Lo stesso pattern si applica a tutti i servizi specifici per le risorse nell'API Google Ads:

• AdGroup: passa un AdGroupOperation a AdGroupService.MutateAdGroups.
• CampaignCriterion: passa un CampaignCriterionOperation a CampaignCriterionService.MutateCampaignCriteria.

Il seguente payload JSON REST illustra una richiesta a 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
}

Operazioni multiple e limitazioni

La maggior parte delle richieste di mutazione specifiche per le risorse accetta un campo operations ripetuto, quindi una singola richiesta può contenere più operazioni per quel tipo di risorsa (fino a 10.000 operazioni per richiesta o 20.000 per AdGroupCriterionService.MutateAdGroupCriteria; CustomerService.MutateCustomer accetta un campo operation singolare). Per impostazione predefinita, tutte le operazioni nella richiesta vengono eseguite in modo atomico, a meno che il servizio non supporti partial_failure e tu lo imposti su true.

Tuttavia, i servizi di risorse individuali presentano due importanti limitazioni:

• Tipo di risorsa singolo:una richiesta a un servizio di risorse può modificare solo le risorse gestite da quel servizio specifico.
• Nessun ID temporaneo tra risorse diverse:poiché una chiamata mutate specifica per una risorsa accetta un solo tipo di risorsa, non puoi assegnare un ID negativo temporaneo a una risorsa principale (ad esempio customers/CUSTOMER_ID/campaigns/-1) e farvi riferimento da una risorsa secondaria di un tipo diverso (ad esempio AdGroup) nella stessa richiesta. Gli ID temporanei autoreferenziali all'interno dello stesso tipo di risorsa sono supportati per gli alberi gerarchici come i gruppi di schede AdGroupCriterion e i nodi AssetGroupListingGroupFilter.

Se devi modificare più tipi di risorse in una singola richiesta o fare riferimento a nomi di risorse temporanei in diversi tipi di risorse, utilizza GoogleAdsService.Mutate.

Differenze specifiche della versione

Tieni presente la seguente differenza tra le versioni dell'API Google Ads supportate quando modifiche alle risorse:

• Servizi di obiettivi basati sul ciclo di vita:gli obiettivi di fidelizzazione dei clienti vengono modificati in tutte le versioni supportate tramite GoalService.MutateGoals (retention_goal_settings) e CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) utilizzando un campo operations ripetuto standard. Nella versione 25 e successive, anche l'acquisizione di nuovi clienti (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) e la fidelizzazione (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) vengono mutate tramite GoalService.MutateGoals e CampaignGoalConfigService.MutateCampaignGoalConfigs. Questo sostituisce CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals e CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, che vengono utilizzati per l'acquisizione di nuovi clienti nelle versioni 23 e 24 e accettano un singolo campo operation.