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

Poiché il campo operations di una richiesta di modifica viene ripetuto, una singola richiesta può contenere più operazioni (fino a 10.000 operazioni per richiesta) per quel tipo di risorsa. Per impostazione predefinita, tutte le operazioni nella richiesta vengono eseguite in modo atomico a meno che tu non imposti partial_failure 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 risorsa temporaneo o riferimento incrociato:le operazioni in una chiamata mutate specifica per la risorsa vengono elaborate in modo indipendente. Non puoi assegnare ID negativi temporanei (ad esempio customers/CUSTOMER_ID/campaigns/-1) o fare riferimento a entità appena create da altre operazioni nella stessa richiesta.

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

Differenze specifiche della versione

Tieni presente le seguenti differenze tra le versioni dell'API Google Ads supportate quando modifiche alle risorse:

• Servizi di obiettivi del ciclo di vita:nella versione 25 e successive, tutti gli obiettivi del ciclo di vita, inclusi Acquisizione di nuovi clienti (new_customer_acquisition_goal_settings), Fidelizzazione dei clienti (retention_goal_settings) e Fidelizzazione (loyalty_retention_goal_settings), vengono modificati tramite GoalService.MutateGoals e CampaignGoalConfigService.MutateCampaignGoalConfigs utilizzando un campo operations ripetuto standard. Questo sostituisce CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals e CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (che vengono utilizzati per l'acquisizione di nuovi clienti nella versione 24 e precedenti e accettano un singolo campo operation).
• Campi di data e ora della campagna:quando crei o aggiorni un Campaign, la versione 23 e successive utilizzano start_date_time e end_date_time (yyyy-MM-dd HH:mm:ss), sostituendo i campi solo data start_date e end_date utilizzati nella versione 22.
• Modificabilità dell'attestazione dei contenuti sintetici:sebbene Asset.synthetic_content_info e Ad.synthetic_content_info vengano visualizzati nello schema per la versione 22 e successive, i campi synthetic_content_info.advertiser_attestation.status e synthetic_content_info.advertiser_attestation.source sono modificabili solo nella versione 23 e successive (system_attestation è sempre OUTPUT_ONLY). Il tentativo di modificare i sottocampi advertiser_attestation nella versione 22 restituisce un errore di campo immutabile ("The field attempted to be mutated is immutable" o "Field cannot be set").