Condividi tramite

Download e caricamento in blocco

  • Articolo

Con il servizio bulk è possibile scaricare e caricare le impostazioni della campagna in modo asincrono in background. Il servizio Bulk è consigliato per la gestione di dati su larga scala, soprattutto se è necessario aggiungere o aggiornare annunci e parole chiave in più gruppi di annunci o campagne in un account. Per alcune entità è anche possibile scaricare i suggerimenti per le offerte e i dati relativi al punteggio di qualità. Ogni record può essere caricato correttamente indipendentemente dal fatto che altri record nello stesso file contengano o meno errori. Per informazioni sullo schema usato per il file di download e caricamento, inclusi i dettagli sulle entità, i suggerimenti di offerta e i dati relativi al punteggio di qualità disponibili, vedere Schema file bulk.

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.

Se si usa un linguaggio .NET, Java o Python, è consigliabile usare le librerie client dell'API Bing Ads. Gli SDK .NET, Java e Python astraggono i dettagli di basso livello descritti di seguito. Ad esempio, invece di chiamare DownloadCampaignsByAccountIds e GetBulkDownloadStatus per scaricare un file, è possibile usare un metodo con la classe BulkServiceManager . Per altre informazioni sull'uso del download bulk e del caricamento con gli SDK, vedere Bulk Service Manager.

Bulk Download

Per scaricare i dati della campagna di un account, chiamare l'operazione DownloadCampaignsByAccountIds . Per scaricare i dati di campagne specifiche, chiamare l'operazione DownloadCampaignsByCampaignIds .

Download di un file bulk

Puoi richiedere tutti i dati della campagna o solo i dati modificati dall'ultima volta che hai scaricato i dati della campagna. Per entrambe le operazioni di download, di seguito è riportata una panoramica delle impostazioni della richiesta e del flusso di lavoro di download.

Importante

È necessario usare le stesse credenziali utente per l'operazione di richiesta di download ( DownloadCampaignsByAccountIds o DownloadCampaignsByCampaignIds) e l'operazione di polling GetBulkDownloadStatus .

  1. Impostare l'elemento DataScope della richiesta e specificare se includere i suggerimenti di offerta o i dati del punteggio di qualità oltre ai dati dell'entità. Per un elenco dei valori possibili, vedere il set di valori DataScope .

  2. Impostare l'elemento DownloadFileType della richiesta per selezionare Csv o Tsv per il formato del file di download.

    Nota

    Il file Csv o Tsv scaricato sarà compresso da ZIP o GZIP a seconda del tipo di compressione specificato. ZIP è l'impostazione predefinita se non è stato specificato CompressionType.

  3. Imposta l'elemento Entities della richiesta per includere le entità della campagna, del gruppo di annunci, degli annunci e delle parole chiave. Facoltativamente, è possibile includere nel download entità aggiuntive, ad esempio parole chiave e destinazioni negative. Per un elenco delle entità che è possibile richiedere, vedere il set di valori DownloadEntity .

  4. Impostare l'elemento LastSyncTimeInUTC della richiesta sul timestamp del download precedente per richiedere solo le entità che sono state aggiornate o eliminate dall'ultimo download.

    Nota

    Se questa è la prima volta che si richiede un download per le entità specificate, impostare l'elemento LastSyncTimeInUTC della richiesta su NULL per scaricare tutte le entità disponibili.

  5. Inviare la richiesta di download con l'operazione DownloadCampaignsByAccountIds o DownloadCampaignsByCampaignIds .

  6. La richiesta di download restituisce un identificatore passato all'operazione GetBulkDownloadStatus . Si chiama l'operazione GetBulkDownloadStatus in un ciclo fino al completamento o all'esito negativo del download. Il tempo necessario per il completamento del download dipende da diverse variabili, ad esempio il numero di campagne richieste e il numero di richieste già presenti nella coda. A causa di queste variabili, l'intervallo di polling usato può variare. Sono disponibili due giorni per scaricare il file dal momento in cui si invia la richiesta di download. Se il file non è stato scaricato correttamente entro questo periodo, viene rimosso dal sito di download e sarà necessario chiamare di nuovo una delle operazioni di download.

  7. Quando l'operazione GetBulkDownloadStatus viene completata correttamente, restituisce l'URL del file di download. Usare l'URL per copiare il file di download in locale. L'URL deve essere usato entro cinque minuti dal momento in cui l'operazione GetBulkDownloadStatus restituisce un codice di stato Operazione riuscita . Se non si avvia il download entro questo periodo di tempo, sarà necessario chiamare nuovamente GetBulkDownloadStatus per ottenere un nuovo URL.

  8. Il file di download è compresso in formato ZIP, quindi è necessario decomprimere il file per accedere ai dati. Per informazioni sullo schema usato per il file di download, vedere Schema file bulk.

Scaricare le procedure consigliate

Attenersi alle procedure consigliate per garantire un utilizzo equo per se stessi e per tutti i client Microsoft Advertising.

Importante

Mentre i limiti di download e caricamento simultanei esatti sono soggetti a modifiche, il numero di richieste in sospeso inviate è limitato. Se si osserva l'errore 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod, è possibile inviare nuovamente la richiesta dopo aver atteso fino a 15 minuti a seconda della frequenza e delle dimensioni delle richieste inviate. Per altre informazioni, vedere Limitazione delle API bulk.

  • Richiedere solo le entità di download bulk necessarie. 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.

  • Eseguire un download completo una sola volta. Successivamente, eseguire i download delta. Impostare LastSyncTimeInUTC sul timestamp dell'ultimo download. Il file di download contiene il timestamp del download nella colonna SyncTime del record account . Non c'è alcun vantaggio nell'eseguire un download completo ogni volta e diminuisce le prestazioni di tutti, incluso il tuo.

  • Eseguire il polling dei download a intervalli ragionevoli. Conosci i tuoi dati meglio di chiunque altro. Se si scarica un account che è ben inferiore a un milione di parole chiave, prendere in considerazione il polling a intervalli da 15 a 20 secondi. Se l'account contiene circa un milione di parole chiave, prendere in considerazione il polling a intervalli di un minuto dopo cinque minuti di attesa. Per gli account con circa quattro milioni di parole chiave, prendere in considerazione il polling a intervalli di un minuto dopo l'attesa di 10 minuti.

  • Chiamare l'operazione DownloadCampaignsByCampaignIds se l'account contiene più di quattro milioni di parole chiave. La chiamata all'operazione DownloadCampaignsByAccountIds con un account che contiene più di quattro milioni di parole chiave avrà esito negativo.

  • È possibile includere meno campagne nella richiesta DownloadCampaignsByCampaignIds . La chiamata all'operazione DownloadCampaignsByCampaignIds con un account che contiene più di otto milioni di parole chiave avrà esito negativo. Le richieste che specificano un minor numero di campagne per chiamata vengono in genere completate prima delle chiamate che specificano il numero massimo consentito.

Caricamento bulk

È possibile inviare il file di caricamento bulk con HTTP POST a un URL fornito dal servizio bulk.

Nota

Il limite di dimensioni del file per il caricamento nell'ambiente di produzione è di 100 MB e fino a 4 milioni di righe. Per Sandbox il limite è di 20.000 righe.

Per informazioni sullo schema da usare per il file di caricamento, vedere Schema file bulk.

Caricamento di un file bulk

Di seguito è riportata una panoramica delle impostazioni della richiesta e del flusso di lavoro di caricamento.

Importante

È necessario usare le stesse credenziali utente in tutto il flusso di lavoro GetBulkUploadUrl, HTTP POST e GetBulkUploadStatus .

  1. Impostare l'elemento AccountId della richiesta GetBulkUploadUrl sull'identificatore dell'account corrispondente ai dati che verranno caricati.

  2. Impostare l'elemento ResponseMode della richiesta GetBulkUploadUrl per specificare se il servizio deve restituire gli errori e i dati corrispondenti oppure solo gli errori nel file dei risultati. Per altre informazioni, vedere ResponseMode.

  3. Usare uploadUrl restituito con la risposta GetBulkUploadUrl per inviare il file di caricamento bulk con HTTP POST. Il tipo di contenuto deve essere multipart/form-data. I file UTF-8 devono includere il indicatore dell'ordine dei byte (BOM). Il caricamento compresso con ZIP deve contenere un file formattato come Csv o Tsv. Il file ZIP deve essere strutturato correttamente, inclusa una fine del record di directory centrale.

    Nota

    L'intestazione Authorization standard HTTP non viene usata. Per eseguire l'autenticazione, è necessario aggiungere e impostare gli elementi di intestazione personalizzati di Microsoft Advertising del client HTTP, incluse le intestazioni DeveloperToken, CustomerId e CustomerAccountId . È anche necessario impostare le credenziali utente tramite l'elemento di intestazione AuthenticationToken . Per altre informazioni, vedere Autenticazione con OAuth e Dove usare le credenziali API.

    È necessario usare le stesse credenziali utente in tutto il flusso di lavoro GetBulkUploadUrl, HTTP POST e GetBulkUploadStatus .

    Ecco un esempio.

    POST <UploadUrl> HTTP/1.1
AuthenticationToken: <AuthenticationToken>
DeveloperToken: <DeveloperToken>
CustomerId: <CustomerId>
AccountId: <AccountId>
Content-Type: multipart/form-data;

  4. Controllare il codice di stato della risposta HTTP. Se il codice di stato della risposta HTTP è 200, il file è stato ricevuto correttamente da Microsoft Advertising. Se il codice di stato della risposta HTTP è 401, l'autenticazione non è riuscita, ad esempio AuthenticationToken o DeveloperToken non è valida. Se il codice di stato della risposta HTTP è 400, è necessario controllare anche il flusso di risposta per i codici di errore dell'operazione dell'API Bing Ads , ad esempio, nell'intervallo compreso tra 3220 e 3227.

    Di seguito è riportato un messaggio di risposta di errore di esempio che indica che l'URL è già stato usato per caricare un file bulk.

    HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
X-AspNetMvc-Version: 3.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 12 Jan 2016 17:07:23 GMT
Content-Length: 224

{"TrackingId":"16bd93cc-22fb-4d3c-94be-25adefd06fae","RequestId":"26c3fbf6-3e24-4569-ada3-d4e8b3d0aecc","Code":3224,"ErrorCode":"BulkServiceUrlAlreadyUsedForUpload","Message":"The URL has already been used for file upload."}

  5. La risposta GetBulkUploadUrl include anche un RequestId passato all'operazione GetBulkUploadStatus . Mentre il caricamento è in sospeso, è possibile chiamare l'operazione GetBulkUploadStatus in un ciclo fino al completamento o all'esito negativo del caricamento. Sono disponibili quindici minuti per scaricare il file dei risultati del caricamento dal momento in cui si invia la richiesta di caricamento. Se il file non è stato scaricato correttamente entro questo periodo, viene rimosso dal sito di download e potrebbe non essere recuperato. Se si perde questa finestra di opportunità, è possibile chiamare una delle operazioni di download per ottenere i dati dell'entità più recenti.

  6. Quando l'operazione GetBulkUploadStatus viene completata correttamente, restituisce l'URL del file dei risultati del caricamento. Usare l'URL per copiare il file dei risultati in locale. L'URL deve essere usato entro quindici minuti dal momento in cui l'operazione GetBulkUploadStatus restituisce la stringa di risposta stato Completed . Se non si avvia il download entro questo periodo di tempo, sarà necessario chiamare nuovamente GetBulkUploadStatus per ottenere un nuovo URL.

    Nota

    Il formato del file dei risultati del caricamento sarà Csv o Tsv e corrisponderà al formato del file inviato per il caricamento.

Caricare le procedure consigliate

Attenersi alle procedure consigliate per garantire un utilizzo equo per se stessi e per tutti i client Microsoft Advertising.

Importante

Mentre i limiti di download e caricamento simultanei esatti sono soggetti a modifiche, il numero di richieste in sospeso inviate è limitato. Se si osserva l'errore 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod, è possibile inviare nuovamente la richiesta dopo aver atteso fino a 15 minuti a seconda della frequenza e delle dimensioni delle richieste inviate. Per altre informazioni, vedere Limitazione delle API bulk.

  • I file di grandi dimensioni possono ridurre le prestazioni di caricamento. È facoltativo e consigliato comprimere il file per il caricamento. Se compresso, deve essere formattato come ZIP con l'estensione corrispondente. Il limite di dimensioni del file per il caricamento nell'ambiente di produzione è di 100 MB e fino a 4 milioni di righe. Per Sandbox il limite è di 20.000 righe. Se è possibile limitare i caricamenti simultanei per cliente al di sotto di 5 o 6, è consigliabile suddividere il file anziché avvicinarsi al limite di dimensioni del file.

  • Limitare i caricamenti simultanei a 5 o 6 per cliente per caricare i file in parallelo. Attendere ogni thread finché il file precedente non è stato elaborato e quindi è possibile riutilizzare il thread per caricare un altro file. Ad esempio, un thread può caricare un file e dopo che lo stato di caricamento è Completed, CompletedWithErrors o Failed tale thread può caricare un altro file.

  • Caricare solo le entità e i campi che si stanno aggiungendo o aggiornando. Se forniti, i campi di sola lettura, ad esempio i suggerimenti per le offerte e i dati sul punteggio di qualità, verranno ignorati.

  • Caricare un tipo di entità per file per ottimizzare le prestazioni. Esistono alcune eccezioni, ad esempio quando si creano nuove campagne, annunci e parole chiave, può essere più efficiente caricarle insieme alle chiavi di riferimento. Come altro esempio, se si aggiornano solo 10 campagne, 500 annunci e 800 parole chiave, è possibile includerli in un caricamento anziché suddividere i caricamenti per tipo.

  • Valutare se è necessario richiedere errori e risultati (ResponseMode = ErrorsAndResults) nel file dei risultati di caricamento o se saranno sufficienti solo gli errori (ResponseMode = ErrorsOnly). Valutare se sincronizzare o meno i risultati con i dati locali. Ad esempio, se si aggiornano le entità, potrebbe essere necessario solo sapere se si sono verificati errori e in questo caso è possibile specificare ResponseMode = ErrorsOnly nella richiesta GetBulkUploadUrl . Se si aggiungono nuove entità, è possibile specificare ResponseMode = ErrorsAndResults nella richiesta GetBulkUploadUrl per ricevere gli identificatori di entità risultanti.

  • Per i tentativi parziali, non caricare l'intero file se solo un subset dei record ha generato errori. Caricare solo i record che si desidera riprovare.

  • Non riprovare fino a quando lo stato di caricamento non è Completato, CompletatoConErrori o Non riuscito. Se per caso le prestazioni non soddisfano le aspettative, attendere comunque il risultato.

  • Eseguire il polling dei risultati del caricamento a intervalli ragionevoli. Inizialmente è necessario attendere un minuto per ogni 10.000 righe caricate. Dopo il tempo di attesa iniziale, prendere in considerazione il polling in intervalli di un minuto.

Vedere anche

Informazioni di riferimento sul servizio bulk
Indirizzi del servizio Web dell'API Bing Ads