Condividi tramite


Operazione del servizio DownloadCampaignsByCampaignIds - Bulk

Scarica le impostazioni e i dati sulle prestazioni per le campagne specificate. È possibile richiedere tutti i dati della campagna o solo i dati modificati dall'ultima volta che è stata scaricata la campagna.

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

Consiglio

Lo schema file bulk fornisce dettagli sui record che è possibile scaricare e caricare. Attenersi alle procedure consigliate per garantire un utilizzo equo per se stessi e per tutti i client Microsoft Advertising. Per informazioni dettagliate, vedere Procedure consigliate per il download bulk e Procedure consigliate per il caricamento bulk.

Elementi della richiesta

L'oggetto DownloadCampaignsByCampaignIdsRequest definisce il corpo e gli elementi di intestazione della richiesta di operazione del servizio. Gli elementi devono essere nello stesso ordine indicato nella richiesta SOAP.

Nota

Se non diversamente indicato di seguito, sono necessari tutti gli elementi della richiesta.

Elementi del corpo della richiesta

Elemento Descrizione Tipo di dati
Campagne Campagne da scaricare. È possibile specificare un massimo di 1.000 campagne. Le campagne specificate devono appartenere allo stesso account. Matrice CampaignScope
CompressionType Tipo di compressione del file di download. Per i valori possibili, vedere CompressionType. Il tipo di compressione predefinito è Zip. CompressionType
DataScope Puoi includere dati sul punteggio di qualità, ad esempio la rilevanza degli annunci, oltre ai dati delle entità, ad esempio le impostazioni della campagna. Il valore predefinito è EntityData.

È possibile includere più valori come flag. Il modo in cui si specificano più flag dipende dal linguaggio di programmazione usato. Ad esempio, C# considera questi valori come valori flag e Java li considera come una matrice di stringhe. Soap deve includere una stringa che contiene un elenco di valori delimitato da spazi, <DataScope>EntityData QualityScoreData</DataScope>ad esempio .

Se BidSuggestionsData o QualityScoreData sono inclusi, è necessario richiedere una sincronizzazione completa. Per eseguire una sincronizzazione completa, non impostare LastSyncTimeInUTC , ad esempio, lasciare nullo.
DataScope
DownloadEntities Entità da includere nel download. Per un elenco delle entità che è possibile scaricare, vedere il set di valori DownloadEntity .

È necessario specificare almeno un'entità di download e in caso contrario l'operazione verrà eseguita in modo errato.
Matrice DownloadEntity
DownloadFileType Formato del file di download. Per i valori possibili, vedere DownloadFileType. Il valore predefinito è CSV. DownloadFileType
FormatVersion Formato per i record del file di download.

Come procedura consigliata è consigliabile specificare sempre la versione del formato più recente. Attualmente l'unica versione di formato supportata per l'API Bing Ads versione 13 è la 6.0.

È consigliabile gestire i record in base allo schema file bulk per la versione del formato corrispondente.
corda
LastSyncTimeInUTC L'ultima volta che è stato richiesto un download. La data e l'ora sono espresse nell'ora UTC (Coordinated Universal Time).

Se si specifica l'ora dell'ultima sincronizzazione, verranno scaricate solo le entità modificate (aggiunte, aggiornate o eliminate) dalla data e dall'ora specificate. Se la campagna o il gruppo di annunci padre è stato eliminato dall'ultima sincronizzazione specificata, verrà visualizzato solo un record eliminato per la campagna o il gruppo di annunci padre eliminato. Ad esempio, se una campagna è stata eliminata, il file bulk non conterrà record eliminati per i gruppi di annunci, i criteri, gli annunci e le parole chiave presenti nella campagna.

Il criterio di destinazione viene trattato in modo leggermente diverso dalle altre entità e i record eliminati non vengono restituiti. Se sono state apportate modifiche alla destinazione di una campagna o di un gruppo di annunci, vengono restituiti tutti i record dei criteri di destinazione secondaria attualmente attivi.

In genere, si richiede un download completo la prima volta che si chiama l'operazione impostando questo elemento su Null. In tutte le chiamate successive si imposta l'ora dell'ultima sincronizzazione sul timestamp del download precedente.

Il file di download contiene il timestamp del download nella colonna Ora di sincronizzazione del record account . È consigliabile usare l'ora di sincronizzazione dell'account per impostare questo elemento la volta successiva in cui si richiede un download.

Se si imposta una data e un'ora superiori a 30 giorni prima, verrà restituito un errore.
dateTime

Elementi dell'intestazione della richiesta

Elemento Descrizione Tipo di dati
AuthenticationToken Token di accesso OAuth che rappresenta le credenziali di un utente che dispone delle autorizzazioni per gli account Microsoft Advertising.

Per altre informazioni, vedere Autenticazione con OAuth.
corda
CustomerAccountId Identificatore dell'account pubblicitario proprietario o associato alle entità nella richiesta. Questo elemento di intestazione deve avere lo stesso valore dell'elemento del corpo AccountId quando sono necessari entrambi. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre.

Per altre informazioni, vedere Ottenere l'account e gli ID cliente.
corda
CustomerId Identificatore dell'account manager (cliente) da cui l'utente accede o opera. Un utente può avere accesso a più account manager. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre.

Per altre informazioni, vedere Ottenere l'account e gli ID cliente.
corda
DeveloperToken Token di sviluppo usato per accedere all'API Bing Ads.

Per altre informazioni, vedere Ottenere un token per sviluppatori.
corda
Password Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. corda
UserName Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. corda

Elementi di risposta

L'oggetto DownloadCampaignsByCampaignIdsResponse definisce il corpo e gli elementi di intestazione della risposta dell'operazione del servizio. Gli elementi vengono restituiti nello stesso ordine illustrato nella soap di risposta.

Elementi del corpo della risposta

Elemento Descrizione Tipo di dati
DownloadRequestId Identificatore della richiesta di download.

Usare l'identificatore per chiamare l'operazione GetBulkDownloadStatus per controllare lo stato del download.

L'identificatore è valido per un massimo di due giorni. Se il file non è stato scaricato correttamente entro questo periodo, viene rimosso dal sito di download e sarà necessario ottenere un nuovo identificatore della richiesta di download.

La stringa ha una lunghezza fino a 40 e può contenere qualsiasi carattere.
corda

Elementi dell'intestazione della risposta

Elemento Descrizione Tipo di dati
TrackingId Identificatore della voce di log che contiene i dettagli della chiamata API. corda

Richiedi SOAP

Questo modello è stato generato da uno strumento per visualizzare l'ordine degli elementi corpo e intestazione per la richiesta SOAP. Per i tipi supportati che è possibile usare con questa operazione del servizio, vedere il riferimento Request Body Elements sopra riportato.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
    <Action mustUnderstand="1">DownloadCampaignsByCampaignIds</Action>
    <AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
    <CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
    <CustomerId i:nil="false">ValueHere</CustomerId>
    <DeveloperToken i:nil="false">ValueHere</DeveloperToken>
  </s:Header>
  <s:Body>
    <DownloadCampaignsByCampaignIdsRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
      <Campaigns i:nil="false">
        <CampaignScope>
          <CampaignId>ValueHere</CampaignId>
          <ParentAccountId>ValueHere</ParentAccountId>
        </CampaignScope>
      </Campaigns>
      <CompressionType i:nil="false">ValueHere</CompressionType>
      <DataScope>ValueHere</DataScope>
      <DownloadEntities i:nil="false">
        <DownloadEntity>ValueHere</DownloadEntity>
      </DownloadEntities>
      <DownloadFileType i:nil="false">ValueHere</DownloadFileType>
      <FormatVersion i:nil="false">ValueHere</FormatVersion>
      <LastSyncTimeInUTC i:nil="false">ValueHere</LastSyncTimeInUTC>
    </DownloadCampaignsByCampaignIdsRequest>
  </s:Body>
</s:Envelope>

SOAP della risposta

Questo modello è stato generato da uno strumento per visualizzare l'ordine degli elementi del corpo e dell'intestazione per la risposta SOAP.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
    <TrackingId d3p1:nil="false" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance">ValueHere</TrackingId>
  </s:Header>
  <s:Body>
    <DownloadCampaignsByCampaignIdsResponse xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
      <DownloadRequestId d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">ValueHere</DownloadRequestId>
    </DownloadCampaignsByCampaignIdsResponse>
  </s:Body>
</s:Envelope>

Sintassi del codice

La sintassi di esempio può essere usata con gli SDK di Bing Ads. Per altri esempi, vedere Esempi di codice DELL'API Bing Ads .

public async Task<DownloadCampaignsByCampaignIdsResponse> DownloadCampaignsByCampaignIdsAsync(
	IList<CampaignScope> campaigns,
	CompressionType? compressionType,
	DataScope dataScope,
	IList<DownloadEntity> downloadEntities,
	DownloadFileType? downloadFileType,
	string formatVersion,
	DateTime? lastSyncTimeInUTC)
{
	var request = new DownloadCampaignsByCampaignIdsRequest
	{
		Campaigns = campaigns,
		CompressionType = compressionType,
		DataScope = dataScope,
		DownloadEntities = downloadEntities,
		DownloadFileType = downloadFileType,
		FormatVersion = formatVersion,
		LastSyncTimeInUTC = lastSyncTimeInUTC
	};

	return (await BulkService.CallAsync((s, r) => s.DownloadCampaignsByCampaignIdsAsync(r), request));
}
static DownloadCampaignsByCampaignIdsResponse downloadCampaignsByCampaignIds(
	ArrayOfCampaignScope campaigns,
	CompressionType compressionType,
	ArrayList<DataScope> dataScope,
	ArrayOfDownloadEntity downloadEntities,
	DownloadFileType downloadFileType,
	java.lang.String formatVersion,
	Calendar lastSyncTimeInUTC) throws RemoteException, Exception
{
	DownloadCampaignsByCampaignIdsRequest request = new DownloadCampaignsByCampaignIdsRequest();

	request.setCampaigns(campaigns);
	request.setCompressionType(compressionType);
	request.setDataScope(dataScope);
	request.setDownloadEntities(downloadEntities);
	request.setDownloadFileType(downloadFileType);
	request.setFormatVersion(formatVersion);
	request.setLastSyncTimeInUTC(lastSyncTimeInUTC);

	return BulkService.getService().downloadCampaignsByCampaignIds(request);
}
static function DownloadCampaignsByCampaignIds(
	$campaigns,
	$compressionType,
	$dataScope,
	$downloadEntities,
	$downloadFileType,
	$formatVersion,
	$lastSyncTimeInUTC)
{

	$GLOBALS['Proxy'] = $GLOBALS['BulkProxy'];

	$request = new DownloadCampaignsByCampaignIdsRequest();

	$request->Campaigns = $campaigns;
	$request->CompressionType = $compressionType;
	$request->DataScope = $dataScope;
	$request->DownloadEntities = $downloadEntities;
	$request->DownloadFileType = $downloadFileType;
	$request->FormatVersion = $formatVersion;
	$request->LastSyncTimeInUTC = $lastSyncTimeInUTC;

	return $GLOBALS['BulkProxy']->GetService()->DownloadCampaignsByCampaignIds($request);
}
response=bulk_service.DownloadCampaignsByCampaignIds(
	Campaigns=Campaigns,
	CompressionType=CompressionType,
	DataScope=DataScope,
	DownloadEntities=DownloadEntities,
	DownloadFileType=DownloadFileType,
	FormatVersion=FormatVersion,
	LastSyncTimeInUTC=LastSyncTimeInUTC)

Requisiti

Servizio: BulkService.svc v13
Namespace: https://bingads.microsoft.com/CampaignManagement/v13

URL richiesta

https://bulk.api.bingads.microsoft.com/Bulk/v13/Campaigns/DownloadByCampaignIds

Elementi della richiesta

L'oggetto DownloadCampaignsByCampaignIdsRequest definisce il corpo e gli elementi di intestazione della richiesta di operazione del servizio.

Nota

Se non diversamente indicato di seguito, sono necessari tutti gli elementi della richiesta.

Elementi del corpo della richiesta

Elemento Descrizione Tipo di dati
Campagne Campagne da scaricare. È possibile specificare un massimo di 1.000 campagne. Le campagne specificate devono appartenere allo stesso account. Matrice CampaignScope
CompressionType Tipo di compressione del file di download. Per i valori possibili, vedere CompressionType. Il tipo di compressione predefinito è Zip. CompressionType
DataScope Puoi includere dati sul punteggio di qualità, ad esempio la rilevanza degli annunci, oltre ai dati delle entità, ad esempio le impostazioni della campagna. Il valore predefinito è EntityData.

È possibile includere più valori come flag. Il modo in cui si specificano più flag dipende dal linguaggio di programmazione usato. Ad esempio, C# considera questi valori come valori flag e Java li considera come una matrice di stringhe. Soap deve includere una stringa che contiene un elenco di valori delimitato da spazi, <DataScope>EntityData QualityScoreData</DataScope>ad esempio .

Se BidSuggestionsData o QualityScoreData sono inclusi, è necessario richiedere una sincronizzazione completa. Per eseguire una sincronizzazione completa, non impostare LastSyncTimeInUTC , ad esempio, lasciare nullo.
DataScope
DownloadEntities Entità da includere nel download. Per un elenco delle entità che è possibile scaricare, vedere il set di valori DownloadEntity .

È necessario specificare almeno un'entità di download e in caso contrario l'operazione verrà eseguita in modo errato.
Matrice DownloadEntity
DownloadFileType Formato del file di download. Per i valori possibili, vedere DownloadFileType. Il valore predefinito è CSV. DownloadFileType
FormatVersion Formato per i record del file di download.

Come procedura consigliata è consigliabile specificare sempre la versione del formato più recente. Attualmente l'unica versione di formato supportata per l'API Bing Ads versione 13 è la 6.0.

È consigliabile gestire i record in base allo schema file bulk per la versione del formato corrispondente.
corda
LastSyncTimeInUTC L'ultima volta che è stato richiesto un download. La data e l'ora sono espresse nell'ora UTC (Coordinated Universal Time).

Se si specifica l'ora dell'ultima sincronizzazione, verranno scaricate solo le entità modificate (aggiunte, aggiornate o eliminate) dalla data e dall'ora specificate. Se la campagna o il gruppo di annunci padre è stato eliminato dall'ultima sincronizzazione specificata, verrà visualizzato solo un record eliminato per la campagna o il gruppo di annunci padre eliminato. Ad esempio, se una campagna è stata eliminata, il file bulk non conterrà record eliminati per i gruppi di annunci, i criteri, gli annunci e le parole chiave presenti nella campagna.

Il criterio di destinazione viene trattato in modo leggermente diverso dalle altre entità e i record eliminati non vengono restituiti. Se sono state apportate modifiche alla destinazione di una campagna o di un gruppo di annunci, vengono restituiti tutti i record dei criteri di destinazione secondaria attualmente attivi.

In genere, si richiede un download completo la prima volta che si chiama l'operazione impostando questo elemento su Null. In tutte le chiamate successive si imposta l'ora dell'ultima sincronizzazione sul timestamp del download precedente.

Il file di download contiene il timestamp del download nella colonna Ora di sincronizzazione del record account . È consigliabile usare l'ora di sincronizzazione dell'account per impostare questo elemento la volta successiva in cui si richiede un download.

Se si imposta una data e un'ora superiori a 30 giorni prima, verrà restituito un errore.
dateTime

Elementi dell'intestazione della richiesta

Elemento Descrizione Tipo di dati
Autorizzazione Token di accesso OAuth che rappresenta le credenziali di un utente che dispone delle autorizzazioni per gli account Microsoft Advertising. Assicurarsi che il token sia preceduto da "Bearer", necessario per l'autenticazione corretta.

Per altre informazioni, vedere Autenticazione con OAuth.
corda
CustomerAccountId Identificatore dell'account pubblicitario proprietario o associato alle entità nella richiesta. Questo elemento di intestazione deve avere lo stesso valore dell'elemento del corpo AccountId quando sono necessari entrambi. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre.

Per altre informazioni, vedere Ottenere l'account e gli ID cliente.
corda
CustomerId Identificatore dell'account manager (cliente) da cui l'utente accede o opera. Un utente può avere accesso a più account manager. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre.

Per altre informazioni, vedere Ottenere l'account e gli ID cliente.
corda
DeveloperToken Token di sviluppo usato per accedere all'API Bing Ads.

Per altre informazioni, vedere Ottenere un token per sviluppatori.
corda
Password Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. corda
UserName Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. corda

Elementi di risposta

L'oggetto DownloadCampaignsByCampaignIdsResponse definisce il corpo e gli elementi di intestazione della risposta dell'operazione del servizio. Gli elementi vengono restituiti nello stesso ordine illustrato nel codice JSON della risposta.

Elementi del corpo della risposta

Elemento Descrizione Tipo di dati
DownloadRequestId Identificatore della richiesta di download.

Usare l'identificatore per chiamare l'operazione GetBulkDownloadStatus per controllare lo stato del download.

L'identificatore è valido per un massimo di due giorni. Se il file non è stato scaricato correttamente entro questo periodo, viene rimosso dal sito di download e sarà necessario ottenere un nuovo identificatore della richiesta di download.

La stringa ha una lunghezza fino a 40 e può contenere qualsiasi carattere.
corda

Elementi dell'intestazione della risposta

Elemento Descrizione Tipo di dati
TrackingId Identificatore della voce di log che contiene i dettagli della chiamata API. corda

Richiedere JSON

Questo modello è stato generato da uno strumento per visualizzare il corpo e gli elementi di intestazione per la richiesta JSON. Per i tipi supportati che è possibile usare con questa operazione del servizio, vedere il riferimento Request Body Elements sopra riportato.

{
  "Campaigns": [
    {
      "CampaignId": "LongValueHere",
      "ParentAccountId": "LongValueHere"
    }
  ],
  "CompressionType": "ValueHere",
  "DataScope": "ValueHere",
  "DownloadEntities": [
    "ValueHere"
  ],
  "DownloadFileType": "ValueHere",
  "FormatVersion": "ValueHere",
  "LastSyncTimeInUTC": "ValueHere"
}

Risposta JSON

Questo modello è stato generato da uno strumento per mostrare il corpo e gli elementi dell'intestazione per la risposta JSON.

{
  "DownloadRequestId": "ValueHere"
}

Sintassi del codice

Per chiamare l'API REST tramite SDK, è necessario aggiornare l'SDK a una determinata versione e configurare i parametri di sistema. La sintassi di esempio può essere usata con gli SDK di Bing Ads. Per altri esempi, vedere Esempi di codice DELL'API Bing Ads .

public async Task<DownloadCampaignsByCampaignIdsResponse> DownloadCampaignsByCampaignIdsAsync(
	IList<CampaignScope> campaigns,
	CompressionType? compressionType,
	DataScope dataScope,
	IList<DownloadEntity> downloadEntities,
	DownloadFileType? downloadFileType,
	string formatVersion,
	DateTime? lastSyncTimeInUTC)
{
	var request = new DownloadCampaignsByCampaignIdsRequest
	{
		Campaigns = campaigns,
		CompressionType = compressionType,
		DataScope = dataScope,
		DownloadEntities = downloadEntities,
		DownloadFileType = downloadFileType,
		FormatVersion = formatVersion,
		LastSyncTimeInUTC = lastSyncTimeInUTC
	};

	return (await BulkService.CallAsync((s, r) => s.DownloadCampaignsByCampaignIdsAsync(r), request));
}
static DownloadCampaignsByCampaignIdsResponse downloadCampaignsByCampaignIds(
	ArrayOfCampaignScope campaigns,
	CompressionType compressionType,
	ArrayList<DataScope> dataScope,
	ArrayOfDownloadEntity downloadEntities,
	DownloadFileType downloadFileType,
	java.lang.String formatVersion,
	Calendar lastSyncTimeInUTC) throws RemoteException, Exception
{
	DownloadCampaignsByCampaignIdsRequest request = new DownloadCampaignsByCampaignIdsRequest();

	request.setCampaigns(campaigns);
	request.setCompressionType(compressionType);
	request.setDataScope(dataScope);
	request.setDownloadEntities(downloadEntities);
	request.setDownloadFileType(downloadFileType);
	request.setFormatVersion(formatVersion);
	request.setLastSyncTimeInUTC(lastSyncTimeInUTC);

	return BulkService.getService().downloadCampaignsByCampaignIds(request);
}
static function DownloadCampaignsByCampaignIds(
	$campaigns,
	$compressionType,
	$dataScope,
	$downloadEntities,
	$downloadFileType,
	$formatVersion,
	$lastSyncTimeInUTC)
{

	$GLOBALS['Proxy'] = $GLOBALS['BulkProxy'];

	$request = new DownloadCampaignsByCampaignIdsRequest();

	$request->Campaigns = $campaigns;
	$request->CompressionType = $compressionType;
	$request->DataScope = $dataScope;
	$request->DownloadEntities = $downloadEntities;
	$request->DownloadFileType = $downloadFileType;
	$request->FormatVersion = $formatVersion;
	$request->LastSyncTimeInUTC = $lastSyncTimeInUTC;

	return $GLOBALS['BulkProxy']->GetService()->DownloadCampaignsByCampaignIds($request);
}
response=bulk_service.DownloadCampaignsByCampaignIds(
	Campaigns=Campaigns,
	CompressionType=CompressionType,
	DataScope=DataScope,
	DownloadEntities=DownloadEntities,
	DownloadFileType=DownloadFileType,
	FormatVersion=FormatVersion,
	LastSyncTimeInUTC=LastSyncTimeInUTC)