Bulk File Schema
Lo schema bulk definisce il contenuto del file per il download o il caricamento con l'API bulk. Sia per il download che per il caricamento, il servizio Bulk supporta i tipi di file e gli schemi corrispondenti nel set di valori DownloadEntity .
Per altre informazioni sull'uso del servizio bulk per gestire le campagne, vedere Download e caricamento in blocco. Per altre informazioni sul contenuto del file di dati, vedere le sezioni seguenti.
- File Schema
- Formato delle versioni
- Tipi di record
- Gerarchia dei tipi
- Chiavi di riferimento
- Identificatori client
- Errori
File Schema
È possibile scegliere di scaricare un set di record delimitato da tabulazioni o virgole (righe) e campi (colonne). La prima intestazione di colonna è denominata Type. Il resto dei nomi delle colonne viene mappato alle proprietà all'interno o associate al tipo di record corrispondente.
Importante
I nuovi tipi di record (righe) e i campi (colonne) possono essere aggiunti in qualsiasi momento e non è consigliabile dipendere dall'ordine dei record o dei campi nel file dei risultati del download bulk o del caricamento bulk. Analogamente, se non diversamente indicato nella documentazione di riferimento, non è consigliabile dipendere da un set fisso di valori restituiti in ogni campo.
Analogamente, durante il caricamento è possibile inviare i campi in qualsiasi ordine. L'ordine dei record di caricamento è importante quando si creano nuove entità, come descritto di seguito all'interno della gerarchia dei tipi.
Formato delle versioni
La versione del formato bulk è separata dalla versione dell'API Bing Ads. La versione del formato consente a un percorso di aggiornamento flessibile di adottare le funzionalità supportate più recenti senza interrompere l'applicazione. Come procedura consigliata, è consigliabile eseguire sempre l'aggiornamento alla versione più recente del formato. Attualmente l'unica versione di formato supportata è la 6.0.
Per specificare la versione del formato di file usando il download bulk, impostare FormatVersion su 6.0 nella richiesta DownloadCampaignsByAccountIds o DownloadCampaignsByCampaignIds .
Per specificare la versione usando il caricamento bulk, impostare il campo Nome del record versione formato su 6.0.
Tipi di record
I record disponibili per il caricamento e il download con formato versione 6.0 sono descritti in dettaglio nella tabella seguente.
Importante
I nuovi tipi di record (righe) e i campi (colonne) possono essere aggiunti in qualsiasi momento e non è consigliabile dipendere dall'ordine dei record o dei campi nel file dei risultati del download bulk o del caricamento bulk.
Gerarchia dei tipi
Il file di download includerà sempre un record per i tipi di record Formato versione e Account . Per il caricamento, la versione del formato è obbligatoria e deve precedere tutti gli altri tipi di record nel file bulk.
Se un'entità padre viene creata nello stesso file, deve precedere tutti i record figlio dipendenti nel file bulk. Ad esempio, come illustrato nel diagramma seguente, quando si associa un'estensione dell'annuncio del collegamento del sito a una campagna, il record dell'estensione ad sitelink campagna deve essere incluso nel file dopo i record dell'estensione campagna e sitelink. I campi ID e ID padre del record dell'estensione pubblicitaria Campaign Sitelink devono essere impostati rispettivamente sull'identificatore dell'estensione ad Sitelink e sui record campagna . Se anche i record dell'estensione ad Sitelink e della campagna sono nuovi e non sono ancora stati assegnati identificatori di Microsoft Advertising, è consigliabile usare le chiavi di riferimento.
Non è necessario includere il record per un'entità padre a cui è già stato assegnato un identificatore di Microsoft Advertising valido.
L'esito positivo parziale è supportato durante l'aggiunta, l'aggiornamento e l'eliminazione di record di file bulk. Ad esempio, se si tenta di aggiungere tre campagne e solo due sono specificate correttamente nel file, ne verranno aggiunte due. Il file dei risultati includerà i dettagli per i record campagna riusciti, un record campagna tentato e un record di errore campagna .
Se il nuovo identificatore della campagna non è ancora noto, ad esempio quando si aggiunge una campagna, un gruppo di annunci, un annuncio di testo e una parola chiave nello stesso file, specificare il nome della campagna come chiave di riferimento logico per tutti i record figlio. Non è necessario specificare un elemento padre esistente nel caricamento.
Gli aggiornamenti parziali sono supportati per i record bulk, inclusi parole chiave negative, siti negativi e criteri di destinazione. Ad esempio, puoi aggiornare l'offerta di un singolo criterio di posizione e non devi scaricare e caricare l'intero set di criteri di destinazione per la campagna o il gruppo di annunci.
Quando si aggiorna un record, è necessario il campo Id per il record aggiornato. È necessario anche l'ID padre o le chiavi di riferimento al record padre.
Quando si aggiorna il nome della campagna o del gruppo di annunci, è facoltativo specificare il nuovo nome per i record figlio se viene specificato l'ID padre corretto.
Se si sostituisce un set di record con un altro set, è necessario specificare i record eliminati prima del nuovo set. Ad esempio, per sostituire tutte le parole chiave negative della campagna esistenti per una determinata campagna, includere prima una parola chiave negativa campagna con stato impostato su Eliminato e ID padre impostato sull'ID campagna. Se non si specifica alcun ID , ad esempio, non tentare di eliminare una parola chiave negativa camapaign specifica, verranno eliminate tutte le parole chiave negative della campagna per tale campagna. Sotto il record "elimina tutto", è possibile includere uno o più nuovi record Campaign Negative Keyword con tutte le proprietà necessarie per l'operazione di caricamento.Below the "delete all" record, you can include one or more campaign negative keyword records with all of the required properties for the upload add operation.
Se si sostituisce un record esistente con un nuovo record con le stesse proprietà univoche, è necessario specificare il record eliminato prima del nuovo record. Ad esempio, per sostituire una destinazione pubblicitaria di Ricerca dinamica del gruppo di annunci esistente per un determinato gruppo di annunci, includere prima di tutto una destinazione ad ricerca dinamica del gruppo di annunci con Stato impostato su Eliminato, ID impostato sull'ID di destinazione dinamica (criterio pagina Web) esistente e ID padre impostato sull'ID del gruppo di annunci. Sotto il record eliminato, è possibile includere un nuovo record ad target di Ricerca dinamica gruppo di annunci (presumibilmente con nuove condizioni della pagina Web).
Nota
Nella maggior parte dei casi è possibile aggiornare il record esistente anziché inviare record di eliminazione e aggiunta separati, ad esempio è possibile aggiornare il campo Rettifica offerta di un criterio di genere campagna esistente.
Quando si elimina un record, il campo ID è obbligatorio. È necessario anche un riferimento all'entità padre, indipendentemente dal fatto che il valore sia un identificatore di sistema assegnato da Microsoft Advertising o chiavi di riferimento per il record padre. Ad esempio, quando si elimina un gruppo di annunci, il campo ID padre del record gruppo di annunci deve corrispondere al campo Id nel record Campagna o il campo Campagna del record Gruppo di annunci deve corrispondere al campo Campagna nel record Campagna . Se vengono forniti entrambi, il campo ID padre del record gruppo di annunci (chiavi di riferimento) viene ignorato.
Con alcune eccezioni, il file dei risultati includerà solo le colonne caricate. Ad esempio, se si carica una nuova parola chiave negativa del gruppo di annunci senza l'intestazione di colonna Id , il file di risultati non includerà l'identificatore assegnato per la nuova parola chiave negativa. Il file bulk deve contenere la colonna ID . tuttavia, è consigliabile lasciare l'ID vuoto per ogni nuova parola chiave negativa del gruppo di annunci. Le eccezioni a questa regola sono campagne, gruppi di annunci, annunci e parole chiave, nel qual caso il file dei risultati conterrà tutte le colonne indipendentemente dalle colonne caricate.
Eseguire l'aggiornamento con delete_value
Per rimuovere un'impostazione esistente, non è consigliabile scrivere una stringa vuota ("") nel file bulk perché tali stringhe vengono ignorate dal servizio Bulk. Usare la stringa riservata "delete_value" per eliminare o reimpostare il valore di un campo facoltativo.
- Se si usa la stringa riservata "delete_value" in un campo facoltativo, l'impostazione precedente verrà eliminata. Ad esempio, se imposti il campo Parametro personalizzato del record gruppo di annunci su "delete_value", tutti i parametri personalizzati precedenti verranno eliminati dal gruppo di annunci. Analogamente, se imposti il campo Modello di rilevamento del record del gruppo di annunci su "delete_value", il modello di rilevamento precedente verrà eliminato dal gruppo di annunci.
- Gli SDK di Bing Ads per .NET, Java e Python scrivono automaticamente "delete_value" se applicabile. Per altri dettagli, vedere Bulk Service Manager - Update with delete_value (Gestione servizi bulk - Aggiornamento con delete_value).
Se si usa "delete_value" nei campi obbligatori, tenere presente quanto segue.
- Se si usa la stringa riservata "delete_value" al posto di un valore primitivo obbligatorio, verrà ignorata. Anche se il campo non è stato aggiornato, la stringa "delete_value" verrà passata tramite il file dei risultati del caricamento. Ad esempio, se imposti il campo Gruppo di annunci (nome gruppo di annunci) del record del gruppo di annunci su "delete_value", il nome del gruppo di annunci non verrà aggiornato.
- Se si usa la stringa riservata "delete_value" al posto di un set di valori obbligatorio, il campo verrà aggiornato al valore predefinito e il file dei risultati rifletterà tale modifica. Ad esempio, se imposti il campo Distribuzione di rete del record gruppo di annunci su "delete_value", la distribuzione di rete del gruppo di annunci verrà impostata su OwnedAndOperatedAndSyndicatedSearch e il file dei risultati del caricamento rifletterà lo stesso.
Chiavi di riferimento
Quando si fa riferimento a un record precedente nel file bulk che non dispone ancora di un identificatore Microsoft Advertising assegnato, è possibile usare una chiave di riferimento logica o una chiave di riferimento negativa a seconda del tipo di record.
Nota
Se l'entità padre viene creata nello stesso file, deve precedere tutti i record figlio dipendenti nel file bulk.
Chiave di riferimento negativa
Quando si fa riferimento a un record precedente nel file bulk a cui non è ancora assegnato un identificatore Microsoft Advertising, è possibile impostare il campo ID dell'estensione su un numero negativo di propria scelta. Questo ID personalizzato è noto come chiave di riferimento negativa. È quindi possibile usare la chiave di riferimento negativa all'interno del campo Id di un record dipendente.
Il primo esempio mostra come creare un gruppo di annunci per una nuova campagna. Impostare il campo ID padre nel record gruppo di annunci sulla chiave di riferimento negativa della campagna (-111). Se si aggiungeranno altri record nello stesso file che devono avere il gruppo di annunci come padre (ad esempio , parola chiave o estensione annunci callout gruppo di annunci), è necessario impostare anche il campo Id nel gruppo di annunci su un valore negativo, ad esempio -1111 a cui è possibile fare riferimento dai record figlio.
| Tipo | Id | Parent Id |
|---|---|---|
| Campagna | -111 | |
| Gruppo di annunci | -1111 | -111 |
Il secondo esempio mostra come creare un'estensione per annunci callout campagna per una nuova campagna e una nuova estensione per annunci callout. L'esempio mostra anche come creare un'estensione ad callout del gruppo di annunci per un nuovo gruppo di annunci e un'altra nuova estensione per annunci callout.
- Impostare il campo ID padre nel record Dell'estensione annuncio callout campagna sulla chiave di riferimento negativa della campagna (-111) e impostare il campo Id nel record Dell'estensione annuncio callout campagna sulla chiave di riferimento negativa dell'estensione annuncio callout (-11).
- Impostare il campo ID padre nel record dell'estensione ad callout del gruppo di annunci sulla chiave di riferimento negativa del gruppo di annunci (-1111) e impostare il campo Id nel record dell'estensione ad callout del gruppo di annunci pubblicitari sulla chiave di riferimento negativa dell'estensione annuncio callout (-12).
| Tipo | Id | Parent Id |
|---|---|---|
| Estensione annuncio callout | -11 | |
| Estensione annuncio callout | -12 | |
| Campagna | -111 | |
| Gruppo di annunci | -1111 | -111 |
| Estensione annuncio callout campagna | -11 | -111 |
| Estensione annunci callout del gruppo di annunci | -12 | -1111 |
Chiave di riferimento logico
Quando si fa riferimento a un nuovo record campagna o gruppo di annunci , è possibile usare il nome della campagna e del gruppo di annunci anziché impostare il campo ID padre su una chiave di riferimento negativa all'interno del record figlio. Ad esempio, per aggiungere un nuovo gruppo di annunci a una nuova campagna e aggiungere una nuova parola chiave al nuovo gruppo di annunci, impostare i campi Campagna e Gruppo di annunci nei record figlio, come illustrato nell'esempio seguente.
| Tipo | Campagna | Gruppo di annunci |
|---|---|---|
| Campagna | Scarpe da donna | |
| Gruppo di annunci | Scarpe da donna | Vendita scarpe rosse da donna |
Identificatori client
Gli identificatori client possono essere usati per associare i record di input nel file di caricamento bulk ai record di output nel file dei risultati. Ad esempio, quando si aggiungono nuovi record, è possibile impostare il campo ID client su un valore stringa di propria scelta. Il sistema Microsoft Advertising non apporta alcuna modifica agli identificatori client e li passa al file dei risultati per il record corrispondente.
Errori
Il file di download bulk o il file dei risultati del caricamento bulk può contenere record in cui il campo Tipo corrispondente include il suffisso Error. Ad esempio, un tipo di record Product Ad Error rappresenta un errore di annuncio del prodotto. Le colonne Error e Error Number contengono i dettagli sull'errore.
Nota
Il file dei risultati del caricamento può includere più record di errore corrispondenti a un record caricato.
Gli errori relativi alle nuove funzionalità, ad esempio GLI URL finali, includeranno dettagli aggiuntivi sulla posizione in cui si è verificato l'errore nella colonna Percorso campo . Ogni nome di percorso del campo corrisponde a un elemento di uno degli oggetti dati del Servizio gestione campagne . Ad esempio, se il campo Modello di rilevamento di un record campagna non inizia con http:// o https://, {lpurl}, o {unescapedlpurl}, il valore di questo valore di Field Path è TrackingTemplate. TrackingUrlTemplate è un elemento dell'oggetto dati Campaign disponibile con il servizio di gestione della campagna.
| Tipo | Modello di rilevamento | Error | Number | Percorso campo |
|---|---|---|---|---|
| Errore campagna | tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} | InvalidUrlScheme | 4600 | TrackingTemplate |
| Errore campagna | tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} | CampaignServiceInvalidUrl | 2611 | TrackingTemplate |
Importante
Il valore Percorso campo è soggetto a modifiche, quindi non è consigliabile accettare una dipendenza dal formato stringa corrente. Il percorso del campo non è supportato per tutti gli errori. È supportato per i campi URL finale per dispositivi mobili, URL finale, modello di rilevamento e parametro personalizzato dei rispettivi record campaign, ad group, expanded text ad, product ad, product partition, keyword e sitelink ad extension . È supportato anche per gli errori relativi a tutti i campi dell'estensione per annunci callout e dei record di revisione dell'estensione per gli annunci .
Se il problema è correlato a un errore editoriale, anche le colonne Posizione editoriale, Termine editoriale, Codice motivo editoriale e Paesi di pubblicazione potrebbero contenere altre informazioni sull'errore.