Service Manager em massa
Tire partido do Serviço em massa para gerir eficientemente grupos de anúncios e anúncios para todas as campanhas numa conta. Os SDKs .NET, Java e Python de Anúncios do Bing fornecem classes para acelerar a produtividade para transferir e carregar registos em massa. Por exemplo, o BulkServiceManager submeterá o seu pedido de transferência para o serviço em massa, consultará o serviço até estar concluído e transferirá o ficheiro para o diretório local. O BulkServiceManager também processa os campos de cabeçalho do pedido comuns automaticamente, permitindo especificar as propriedades Autenticação, CustomerId, AccountId e DeveloperToken no objeto AuthorizationData uma vez para cada serviço. Para obter mais informações, veja Utilizar AuthorizationData e o exemplo de código Pedidos em Massa .
Nota
O BulkServiceManager só está disponível com os SDKs .NET, Java e Python do Bing Ads. Quer utilize ou não um SDK, pode utilizar o Serviço em massa diretamente. Para obter mais informações, veja Transferência e Carregamento em Massa.
Leitor e Escritor de Ficheiros em Massa
Não precisa de implementar o seu próprio analisador de ficheiros para ler e escrever o ficheiro em massa. Pode utilizar objetos BulkFileReader e BulkFileWriter para ler e escrever classes derivadas de BulkEntity .
Nota
O BulkServiceManager utiliza um BulkFileReader e o BulkFileWriter em segundo plano quando carrega e transfere entidades em vez de ficheiros. Os ficheiros temporários são utilizados em segundo plano. Para obter mais detalhes, veja Diretório de Trabalho e BulkServiceManager.
Por exemplo, digamos que pretende escrever o seguinte registo de Anúncio de Texto Expandido num ficheiro em massa.
Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Title,Text,Text Part 2,Display Url,Destination Url,Promotion,Device Preference,Ad Format Preference,Name,App Platform,App Id,Final Url,Mobile Final Url,Tracking Template,Custom Parameter,Title Part 1,Title Part 2,Title Part 3,Path 1,Path 2
Format Version,,,,,,,,,,,,,,,6.0,,,,,,,,,,,
Expanded Text Ad,Active,,-1111,ParentCampaignNameGoesHere,AdGroupNameGoesHere,ClientIdGoesHere,,,Find New Customers & Increase Sales!,Start Advertising on Contoso Today.,,,,,False,,,,https://www.contoso.com/womenshoesale,https://mobile.contoso.com/womenshoesale,,{_promoCode}=PROMO1; {_season}=summer,Contoso,Quick & Easy Setup,Seemless Integration,seattle,shoe sale
Em primeiro lugar, crie o objeto BulkExpandedTextAd, conforme mostrado abaixo no Mapa de Entidades de Gestão de Campanhas e Em Massa. Em seguida, pode escrever o BulkExpandedTextAd num ficheiro com BulkFileWriter, conforme mostrado aqui.
var bulkFileWriter = new BulkFileWriter(
filePath: FileDirectory + UploadFileName
);
bulkFileWriter.WriteEntity(bulkExpandedTextAd);
bulkFileWriter.Dispose();
BulkFileWriter bulkFileWriter = new BulkFileWriter(
new File(FileDirectory + UploadFileName)
);
bulkFileWriter.writeEntity(bulkExpandedTextAd);
bulkFileWriter.close();
bulk_file_writer=BulkFileWriter(
file_path=FILE_DIRECTORY+UPLOAD_FILE_NAME
)
bulk_file_writer.write_entity(bulk_expanded_text_ad)
bulk_file_writer.close()
Eis um exemplo de leitura do ficheiro de resultados de carregamento em massa a partir de um diretório local com BulkFileReader. Pode ler um ficheiro em massa com o BulkFileReader, seja transferência completa, transferência parcial ou carregamento de resultados.
var bulkFileReader = new BulkFileReader(
filePath: bulkFilePath, // Path to the Bulk file
resultFileType: ResultFileType.Upload, // FullDownload, PartialDownload, or Upload
fileFormat: DownloadFileType.Csv // Csv or Tsv
);
var resultEntities = bulkFileReader.ReadEntities().ToList();
var expandedTextAdResults = resultEntities.OfType<BulkExpandedTextAd>().ToList();
OutputBulkExpandedTextAds(expandedTextAdResults);
bulkFileReader.Dispose();
BulkFileReader bulkFileReader = new BulkFileReader(
bulkFilePath, // Path to the Bulk file
ResultFileType.UPLOAD, // FULL_DOWNLOAD, PARTIAL_DOWNLOAD, or UPLOAD
DownloadFileType.CSV // Csv or Tsv
);
BulkEntityIterable resultEntities = bulkFileReader.getEntities();
for (BulkEntity entity : resultEntities) {
if (entity instanceof BulkExpandedTextAd) {
outputBulkBulkExpandedTextAds(Arrays.asList((BulkExpandedTextAd) entity));
}
}
resultEntities.close();
bulkFileReader.close();
def read_entities_from_bulk_file(file_path, result_file_type, file_type):
with BulkFileReader(file_path=file_path, result_file_type=result_file_type, file_type=file_type) as reader:
for entity in reader:
yield entity
def main():
result_entities=[]
entities_generator=read_entities_from_bulk_file(
file_path=bulk_file_path, # Path to the Bulk file
result_file_type=ResultFileType.upload, # full_download, partial_download, or upload
file_type='Csv' # Csv or Tsv
)
for entity in entities_generator:
result_entities.append(entity)
for entity in download_entities:
if isinstance(entity, BulkExpandedTextAd):
output_bulk_expanded_text_ads([entity])
Mapa de Entidades de Gestão de Campanhas e Em Massa
Todos os objetos lidos e escritos em ficheiros em massa através de BulkServiceManager, BulkFileReader, BulkFileWriter derivam da classe base BulkEntity, por exemplo, BulkCampaign, BulkAdGroup e BulkExpandedTextAd. Sempre que possível, os objetos em massa tiram partido dos objetos e conjuntos de valores da Gestão de Campanhas, por exemplo, o seguinte BulkExpandedTextAd contém o objeto ExpandedTextAd da API de Gestão de Campanhas.
var uploadEntities = new List<BulkEntity>();
// Map properties in the Bulk file to the BulkExpandedTextAd
var bulkExpandedTextAd = new BulkExpandedTextAd
{
// 'Parent Id' column header in the Bulk file
AdGroupId = adGroupIdKey,
// 'Ad Group' column header in the Bulk file
AdGroupName = "AdGroupNameGoesHere",
// 'Campaign' column header in the Bulk file
CampaignName = "ParentCampaignNameGoesHere",
// 'Client Id' column header in the Bulk file
ClientId = "ClientIdGoesHere",
// Map properties in the Bulk file to the
// ExpandedTextAd object of the Campaign Management service.
ExpandedTextAd = new ExpandedTextAd
{
// 'Ad Format Preference' column header in the Bulk file
AdFormatPreference = "All",
// 'Mobile Final Url' column header in the Bulk file
FinalMobileUrls = new[] {
// Each Url is delimited by a semicolon (;) in the Bulk file
"https://mobile.contoso.com/womenshoesale"
},
// 'Final Url' column header in the Bulk file
FinalUrls = new[] {
// Each Url is delimited by a semicolon (;) in the Bulk file
"https://www.contoso.com/womenshoesale"
},
// 'Id' column header in the Bulk file
Id = null,
// 'Path 1' column header in the Bulk file
Path1 = "seattle",
// 'Path 2' column header in the Bulk file
Path2 = "shoe sale",
// 'Status' column header in the Bulk file
Status = AdStatus.Active,
// 'Text' column header in the Bulk file
Text = "Find New Customers & Increase Sales!",
// 'Text Part 2' column header in the Bulk file
TextPart2 = "Start Advertising on Contoso Today.",
// 'Title Part 1' column header in the Bulk file
TitlePart1 = "Contoso",
// 'Title Part 2' column header in the Bulk file
TitlePart2 = "Quick & Easy Setup",
// 'Title Part 3' column header in the Bulk file
TitlePart3 = "Seemless Integration",
// 'Tracking Template' column header in the Bulk file
TrackingUrlTemplate = null,
// 'Custom Parameter' column header in the Bulk file
UrlCustomParameters = new CustomParameters
{
// Each custom parameter is delimited by a semicolon (;) in the Bulk file
Parameters = new[] {
new CustomParameter(){
Key = "promoCode",
Value = "PROMO1"
},
new CustomParameter(){
Key = "season",
Value = "summer"
},
}
},
},
};
uploadEntities.Add(bulkExpandedTextAd);
var entityUploadParameters = new EntityUploadParameters
{
Entities = uploadEntities,
ResponseMode = ResponseMode.ErrorsAndResults,
ResultFileDirectory = FileDirectory,
ResultFileName = DownloadFileName,
OverwriteResultFile = true,
};
var uploadResultEntities = (await bulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();
List<BulkEntity> uploadEntities = new ArrayList<BulkEntity>();
// Map properties in the Bulk file to the BulkExpandedTextAd
BulkExpandedTextAd bulkExpandedTextAd = new BulkExpandedTextAd();
// 'Parent Id' column header in the Bulk file
bulkExpandedTextAd.setAdGroupId(adGroupIdKey);
// 'Ad Group' column header in the Bulk file
bulkExpandedTextAd.setAdGroupName("AdGroupNameGoesHere");
// 'Campaign' column header in the Bulk file
bulkExpandedTextAd.setCampaignName("ParentCampaignNameGoesHere");
// 'Client Id' column header in the Bulk file
bulkExpandedTextAd.setClientId("ClientIdGoesHere");
// Map properties in the Bulk file to the
// ExpandedTextAd object of the Campaign Management service.
ExpandedTextAd expandedTextAd = new ExpandedTextAd();
// 'Ad Format Preference' column header in the Bulk file
expandedTextAd.setAdFormatPreference("All");
// 'Mobile Final Url' column header in the Bulk file
// Each Url is delimited by a semicolon (;) in the Bulk file
ArrayOfstring mobileFinalUrls = new ArrayOfstring();
mobileFinalUrls.getStrings().add("https://mobile.contoso.com/womenshoesale");
expandedTextAd.setFinalMobileUrls(mobileFinalUrls);
// 'Final Url' column header in the Bulk file
// Each Url is delimited by a semicolon (;) in the Bulk file
ArrayOfstring finalUrls = new ArrayOfstring();
finalUrls.getStrings().add("https://www.contoso.com/womenshoesale");
expandedTextAd.setFinalUrls(finalUrls);
// 'Id' column header in the Bulk file
expandedTextAd.setId(null);
// 'Path 1' column header in the Bulk file
expandedTextAd.setPath1("seattle");
// 'Path 2' column header in the Bulk file
expandedTextAd.setPath2("shoe sale");
// 'Status' column header in the Bulk file
expandedTextAd.setStatus(AdStatus.ACTIVE);
// 'Text' column header in the Bulk file
expandedTextAd.setText("Find New Customers & Increase Sales!");
// 'Text Part 2' column header in the Bulk file
expandedTextAd.setTextPart2("Start Advertising on Contoso Today.");
// 'Title Part 1' column header in the Bulk file
expandedTextAd.setTitlePart1("Contoso");
// 'Title Part 2' column header in the Bulk file
expandedTextAd.setTitlePart2("Quick & Easy Setup");
// 'Title Part 3' column header in the Bulk file
expandedTextAd.setTitlePart3("Seemless Integration");
// 'Tracking Template' column header in the Bulk file
expandedTextAd.setTrackingUrlTemplate(null);
// 'Custom Parameter' column header in the Bulk file
// Each custom parameter is delimited by a semicolon (;) in the Bulk file
CustomParameters customParameters = new CustomParameters();
ArrayOfCustomParameter arrayOfCustomParameter = new ArrayOfCustomParameter();
CustomParameter customParameterA = new CustomParameter();
customParameterA.setKey("promoCode");
customParameterA.setValue("PROMO1");
arrayOfCustomParameter.getCustomParameters().add(customParameterA);
CustomParameter customParameterB = new CustomParameter();
customParameterB.setKey("season");
customParameterB.setValue("summer");
arrayOfCustomParameter.getCustomParameters().add(customParameterB);
customParameters.setParameters(arrayOfCustomParameter);
expandedTextAd.setUrlCustomParameters(customParameters);
bulkExpandedTextAd.setExpandedTextAd(expandedTextAd);
uploadEntities.add(bulkExpandedTextAd);
EntityUploadParameters entityUploadParameters = new EntityUploadParameters();
entityUploadParameters.setEntities(uploadEntities);
entityUploadParameters.setOverwriteResultFile(true);
entityUploadParameters.setResultFileDirectory(new File(FileDirectory));
entityUploadParameters.setResultFileName(ResultFileName);
entityUploadParameters.setResponseMode(ResponseMode.ERRORS_AND_RESULTS);
BulkEntityIterable uploadResultEntities = bulkServiceManager.uploadEntitiesAsync(
entityUploadParameters,
null,
null
).get();
# Map properties in the Bulk file to the BulkExpandedTextAd
bulk_expanded_text_ad=BulkExpandedTextAd()
# 'Parent Id' column header in the Bulk file
bulk_expanded_text_ad.ad_group_id=AD_GROUP_ID_KEY
# 'Ad Group' column header in the Bulk file
bulk_expanded_text_ad.AdGroupName='AdGroupNameGoesHere'
# 'Campaign' column header in the Bulk file
bulk_expanded_text_ad.CampaignName='ParentCampaignNameGoesHere'
# 'Client Id' column header in the Bulk file
bulk_expanded_text_ad.ClientId='ClientIdGoesHere'
# Map properties in the Bulk file to the
# ExpandedTextAd object of the Campaign Management service.
expanded_text_ad=set_elements_to_none(campaign_service.factory.create('ExpandedTextAd'))
# 'Ad Format Preference' column header in the Bulk file
expanded_text_ad.AdFormatPreference='All'
# 'Mobile Final Url' column header in the Bulk file
# Each Url is delimited by a semicolon (;) in the Bulk file
mobile_final_urls=campaign_service.factory.create('ns3:ArrayOfstring')
mobile_final_urls.string.append('https://mobile.contoso.com/womenshoesale')
expanded_text_ad.FinalUrls=mobile_final_urls
# 'Final Url' column header in the Bulk file
# Each Url is delimited by a semicolon (;) in the Bulk file
final_urls=campaign_service.factory.create('ns3:ArrayOfstring')
final_urls.string.append('https://www.contoso.com/womenshoesale')
expanded_text_ad.FinalUrls=final_urls
# 'Id' column header in the Bulk file
expanded_text_ad.Id=None
# 'Path 1' column header in the Bulk file
expanded_text_ad.Path1='seattle'
# 'Path 2' column header in the Bulk file
expanded_text_ad.Path2='shoe sale'
# 'Status' column header in the Bulk file
expanded_text_ad.Status='Active'
# 'Text' column header in the Bulk file
expanded_text_ad.Text='Find New Customers & Increase Sales!'
# 'Text Part 2' column header in the Bulk file
expanded_text_ad.TextPart2='Start Advertising on Contoso Today.'
# 'Title Part 1' column header in the Bulk file
expanded_text_ad.TitlePart1='Contoso'
# 'Title Part 2' column header in the Bulk file
expanded_text_ad.TitlePart2='Quick & Easy Setup'
# 'Title Part 3' column header in the Bulk file
expanded_text_ad.TitlePart3='Seemless Integration'
# 'Tracking Template' column header in the Bulk file
expanded_text_ad.TrackingUrlTemplate=None
# 'Custom Parameter' column header in the Bulk file
# Each custom parameter is delimited by a semicolon (;) in the Bulk file
custom_parameters=set_elements_to_none(campaign_service.factory.create('CustomParameters'))
array_of_custom_parameter=campaign_service.factory.create('ArrayOfCustomParameter')
custom_parameter_a=set_elements_to_none(campaign_service.factory.create('CustomParameter'))
custom_parameter_a.Key='promoCode'
custom_parameter_a.Value='PROMO1'
array_of_custom_parameter.CustomParameter.append(custom_parameter_a)
custom_parameter_b=set_elements_to_none(campaign_service.factory.create('CustomParameter'))
custom_parameter_b.Key='season'
custom_parameter_b.Value='summer'
array_of_custom_parameter.CustomParameter.append(custom_parameter_b)
custom_parameters.Parameters=array_of_custom_parameter
expanded_text_ad.UrlCustomParameters=custom_parameters
bulk_expanded_text_ad.ad=expanded_text_ad
upload_entities.append(bulk_expanded_text_ad)
entity_upload_parameters=EntityUploadParameters(
entities=upload_entities,
overwrite_result_file=True,
result_file_directory=FILE_DIRECTORY,
result_file_name=RESULT_FILE_NAME,
response_mode='ErrorsAndResults'
)
upload_result_entities=bulk_service_manager.upload_entities(
entity_upload_parameters=entity_upload_parameters,
progress=None
)
Atualizar com delete_value
Para remover uma definição existente, não deve escrever uma cadeia vazia ("") no ficheiro em massa porque essas cadeias são ignoradas pelo serviço em massa. Utilize a cadeia reservada "delete_value" para eliminar ou repor o valor de um campo opcional. Se utilizar a cadeia reservada "delete_value" num campo opcional, a definição anterior será eliminada. Por exemplo, se definir o campo Parâmetro Personalizado do registo de Anúncio de Texto Expandido como "delete_value", todos os parâmetros personalizados anteriores serão eliminados do anúncio de texto expandido. Da mesma forma, se definir o campo Modelo de Controlo do registo de Anúncio de Texto Expandido como "delete_value", o modelo de controlo anterior será eliminado do anúncio de texto expandido. Para obter mais detalhes sobre "delete_value", veja Bulk File Schema - Update with delete_value (Esquema de Ficheiros em Massa – Atualizar com delete_value).
O BulkFileWriter escreve automaticamente "delete_value" quando aplicável. Uma vez que o SDK mapeia objetos da API de Gestão de Campanhas para o conteúdo de um ficheiro em massa, não pode definir explicitamente a cadeia "delete_value" para propriedades com outros tipos de dados. Nesses casos, pode utilizar a mesma sintaxe que utilizaria para atualizar o objeto através da API de Gestão de Campanhas. No exemplo abaixo, ao definir UrlCustomParameters como um objeto CustomParameters vazio, o SDK escreverá "delete_value" no campo Parâmetro Personalizado do registo Do Anúncio de Texto Expandido . Da mesma forma, ao definir TrackingUrlTemplate como uma cadeia vazia, o SDK escreverá "delete_value" no campo Modelo de Controlo do registo AD de Texto Expandido . A sintaxe de exemplo no objeto ExpandedTextAd é idêntica à forma como eliminaria as definições previus através da operação do serviço UpdateAds através da API de Gestão de Campanhas.
Importante
Não utilize cadeias vazias ("") ou a sintaxe "delete_value" quando criar uma entidade em Massa. A cadeia reservada "delete_value" só é aplicável para atualizar registos em massa. Não deve definir a propriedade ou defini-la como um equivalente nulo.
var bulkExpandedTextAd = new BulkExpandedTextAd
{
AdGroupId = adGroupIdKey,
ExpandedTextAd = new ExpandedTextAd
{
Id = expandedTextAdIdKey,
TrackingUrlTemplate = "",
UrlCustomParameters = new CustomParameters { }
},
};
BulkExpandedTextAd bulkExpandedTextAd = new BulkExpandedTextAd();
bulkExpandedTextAd.setAdGroupId(expandedTextAdIdKey);
ExpandedTextAd expandedTextAd = new ExpandedTextAd();
expandedTextAd.setId(adIdKey);
expandedTextAd.setTrackingUrlTemplate("");
CustomParameters customParameters = new CustomParameters();
expandedTextAd.setUrlCustomParameters(customParameters);
bulkExpandedTextAd.setExpandedTextAd(expandedTextAd);
bulk_expanded_text_ad=BulkExpandedTextAd()
bulk_expanded_text_ad.ad_group_id=AD_GROUP_ID_KEY
expanded_text_ad=set_elements_to_none(campaign_service.factory.create('ExpandedTextAd'))
expanded_text_ad.Id=EXPANDED_TEXT_AD_ID_KEY
expanded_text_ad.TrackingUrlTemplate=''
custom_parameters=set_elements_to_none(campaign_service.factory.create('CustomParameters'))
expanded_text_ad.UrlCustomParameters=custom_parameters
bulk_expanded_text_ad.ad=expanded_text_ad
Transferir e Carregar
O BulkServiceManager suporta fluxos de trabalho de transferência e carregamento em massa flexíveis.
Pode criar um pedido de transferência ou carregamento e o BulkServiceManager submeterá o seu pedido de transferência para o serviço em massa, consultará o serviço até estar concluído e transferirá o ficheiro para o diretório local. Por exemplo, veja Conclusão em Segundo Plano com BulkServiceManager.
Pode submeter um pedido de transferência ou carregamento e, em seguida, consultar até que o ficheiro de resultados esteja pronto para transferência. Por exemplo, veja Submeter e Transferir com BulkServiceManager.
Se, por algum motivo, tiver de retomar a partir de um estado de aplicação anterior, pode utilizar um identificador de pedido de transferência ou carregamento existente e utilizá-lo para transferir o ficheiro de resultados. Por exemplo, veja Transferir Resultados com BulkServiceManager.
Quer transfira e carregue entidades na memória ou leia e escreva-as num ficheiro manualmente, o BulkServiceManager lê e escreve num ficheiro temporário.
Conclusão em Segundo Plano com BulkServiceManager
Pode criar um pedido de transferência ou carregamento e o BulkServiceManager submeterá o seu pedido de transferência para o serviço em massa, consultará o serviço até estar concluído e transferirá o ficheiro para o diretório local.
public async Task RunAsync(AuthorizationData authorizationData)
{
var bulkServiceManager = new BulkServiceManager(authorizationData);
var progress = new Progress<BulkOperationProgressInfo>(x =>
Console.WriteLine(String.Format("{0} % Complete", x.PercentComplete.ToString(CultureInfo.InvariantCulture))));
var downloadParameters = new DownloadParameters
{
CampaignIds = null,
DataScope = DataScope.EntityData,
Entities = DownloadEntity.Keywords,
FileType = DownloadFileType.Csv,
LastSyncTimeInUTC = null,
ResultFileDirectory = FileDirectory,
ResultFileName = ResultFileName,
OverwriteResultFile = false // Set this value true if you want to overwrite the same file.
};
// Sets the time interval in milliseconds between two status polling attempts. The default value is 5000 (5 seconds).
bulkServiceManager.StatusPollIntervalInMilliseconds = 5000;
// Sets the timeout of the HttpClient download operation. The default value is 100000 (100s).
bulkServiceManager.DownloadHttpTimeout = new TimeSpan(0, 0, 100);
// You may optionally cancel the DownloadFileAsync operation after a specified time interval.
// Pass this object to the DownloadFileAsync operation or specify CancellationToken.None.
var tokenSource = new CancellationTokenSource();
tokenSource.CancelAfter(3600000);
// The BulkServiceManager will submit your download request to the Bulk service,
// poll the service until completed, and download the file to your local directory.
var resultFile = await bulkServiceManager.DownloadFileAsync(
parameters: downloadParameters,
progress: progress,
cancellationToken: tokenSource.Token
);
Console.WriteLine(string.Format("Download result file: {0}\n", resultFile));
}
BulkServiceManager bulkServiceManager = new BulkServiceManager(authorizationData);
Progress<BulkOperationProgressInfo> progress = new Progress<BulkOperationProgressInfo>() {
@Override
public void report(BulkOperationProgressInfo value) {
System.out.println(value.getPercentComplete() + "% Complete\n");
}
};
DownloadParameters downloadParameters = new DownloadParameters();
downloadParameters.setCampaignIds(null);
ArrayList<DataScope> dataScope = new ArrayList<DataScope>();
dataScope.add(DataScope.ENTITY_DATA);
downloadParameters.setDataScope(dataScope);
downloadParameters.setFileType(FileType);
downloadParameters.setLastSyncTimeInUTC(null);
ArrayList<DownloadEntity> bulkDownloadEntities = new ArrayList<DownloadEntity>();
bulkDownloadEntities.add(DownloadEntity.KEYWORDS);
downloadParameters.setEntities(bulkDownloadEntities);
downloadParameters.setResultFileDirectory(new File(FileDirectory));
downloadParameters.setResultFileName(ResultFileName);
downloadParameters.setOverwriteResultFile(true); // Set this value true if you want to overwrite the same file.
// Sets the time interval in milliseconds between two status polling attempts. The default value is 5000 (5 seconds).
bulkServiceManager.setStatusPollIntervalInMilliseconds(5000);
// Sets the timeout of the HttpClient download operation. The default value is 100000 (100s).
bulkServiceManager.setDownloadHttpTimeoutInMilliseconds(100000);
// The BulkServiceManager will submit your download request to the Bulk service,
// poll the service until completed, and download the file to your local directory.
// You may optionally cancel the downloadFileAsync operation after a specified time interval.
File resultFile = bulkServiceManager.downloadFileAsync(
downloadParameters,
progress,
null
).get(3600000, TimeUnit.MILLISECONDS);
System.out.printf("Download result file: %s\n", resultFile.getName());
bulk_service_manager = BulkServiceManager(
authorization_data=authorization_data,
# Sets the time interval in milliseconds between two status polling attempts.
# The default value is 5000 (5 seconds).
poll_interval_in_milliseconds = 5000,
environment = ENVIRONMENT,
)
download_parameters = DownloadParameters(
campaign_ids=None,
data_scope=['EntityData'],
entities=entities,
file_type=FILE_TYPE,
last_sync_time_in_utc=None,
result_file_directory = FILE_DIRECTORY,
result_file_name = DOWNLOAD_FILE_NAME,
# Set this value true if you want to overwrite the same file.
overwrite_result_file = True,
# You may optionally cancel the download after a specified time interval.
timeout_in_milliseconds=3600000
)
# The BulkServiceManager will submit your download request to the Bulk service,
# poll the service until completed, and download the file to your local directory.
result_file_path = bulk_service_manager.download_file(
download_parameters=download_parameters,
progress = None
)
print("Download result file: {0}\n".format(result_file_path))
Submeter e Transferir com o BulkServiceManager
Submeta o pedido de transferência e, em seguida, utilize o resultado BulkDownloadOperation para controlar o estado.
public async Task RunAsync(AuthorizationData authorizationData)
{
var bulkServiceManager = new BulkServiceManager(authorizationData);
var submitDownloadParameters = new SubmitDownloadParameters
{
CampaignIds = null,
DataScope = DataScope.EntityData,
Entities = DownloadEntity.Keywords,
FileType = DownloadFileType.Csv,
LastSyncTimeInUTC = null
};
var bulkDownloadOperation = await bulkServiceManager.SubmitDownloadAsync(submitDownloadParameters);
// You may optionally cancel the TrackAsync operation after a specified time interval.
var tokenSource = new CancellationTokenSource();
tokenSource.CancelAfter(3600000);
BulkOperationStatus<DownloadStatus> downloadStatus = await bulkDownloadOperation.TrackAsync(
null,
tokenSource.Token
);
var resultFilePath = await bulkDownloadOperation.DownloadResultFileAsync(
FileDirectory,
ResultFileName,
decompress: true,
overwrite: true // Set this value true if you want to overwrite the same file.
);
Console.WriteLine(String.Format("Download result file: {0}\n", resultFilePath));
}
BulkServiceManager bulkServiceManager = new BulkServiceManager(authorizationData);
SubmitDownloadParameters submitDownloadParameters = new SubmitDownloadParameters();
submitDownloadParameters.setCampaignIds(null);
ArrayList<DataScope> dataScope = new ArrayList<DataScope>();
dataScope.add(DataScope.ENTITY_DATA);
submitDownloadParameters.setDataScope(dataScope);
submitDownloadParameters.setFileType(FileType);
submitDownloadParameters.setLastSyncTimeInUTC(null);
ArrayList<DownloadEntity> bulkDownloadEntities = new ArrayList<DownloadEntity>();
bulkDownloadEntities.add(DownloadEntity.KEYWORDS);
submitDownloadParameters.setEntities(bulkDownloadEntities);
// Submit the download request. You can use the BulkDownloadOperation result to track status yourself using getStatusAsync,
// or use trackAsync to indicate that the application should wait until the download status is completed.
BulkDownloadOperation bulkDownloadOperation = bulkServiceManager.submitDownloadAsync(
submitDownloadParameters,
null
).get();
// You may optionally cancel the trackAsync operation after a specified time interval.
BulkOperationStatus<DownloadStatus> downloadStatus = bulkDownloadOperation.trackAsync(
null
).get(3600000, TimeUnit.MILLISECONDS);
File resultFile = bulkDownloadOperation.downloadResultFileAsync(
new File(FileDirectory),
ResultFileName,
true, // Set this value to true if you want to decompress the ZIP file.
true, // Set this value true if you want to overwrite the named file.
null
).get();
System.out.println(String.format("Download result file: %s\n", resultFile.getName()));
bulk_service_manager = BulkServiceManager(
authorization_data=authorization_data,
poll_interval_in_milliseconds = 5000,
environment = ENVIRONMENT,
)
submit_download_parameters = SubmitDownloadParameters(
data_scope = [ 'EntityData' ],
entities = [ 'Campaigns', 'AdGroups', 'Keywords', 'Ads' ],
file_type = 'Csv',
campaign_ids = None,
last_sync_time_in_utc = None,
performance_stats_date_range = None
)
bulk_download_operation = bulk_service_manager.submit_download(submit_download_parameters)
# You may optionally cancel the track() operation after a specified time interval.
download_status = bulk_download_operation.track(timeout_in_milliseconds=3600000)
result_file_path = bulk_download_operation.download_result_file(
result_file_directory = FILE_DIRECTORY,
result_file_name = DOWNLOAD_FILE_NAME,
decompress = True,
overwrite = True, # Set this value true if you want to overwrite the same file.
timeout_in_milliseconds=3600000 # You may optionally cancel the download after a specified time interval.
)
print("Download result file: {0}\n".format(result_file_path))
Transferir Resultados com BulkServiceManager
Se, por algum motivo, tiver de retomar a partir de um estado de aplicação anterior, pode utilizar um identificador de pedido de transferência ou carregamento existente e utilizá-lo para transferir o ficheiro de resultados. Controle o resultado para garantir que o estado da transferência está concluído.
public async Task RunAsync(AuthorizationData authorizationData)
{
var bulkServiceManager = new BulkServiceManager(authorizationData);
var progress = new Progress<BulkOperationProgressInfo>(x =>
Console.WriteLine(String.Format("{0} % Complete", x.PercentComplete.ToString(CultureInfo.InvariantCulture))));
// You may optionally cancel the TrackAsync operation after a specified time interval.
var tokenSource = new CancellationTokenSource();
tokenSource.CancelAfter(3600000);
var bulkDownloadOperation = new BulkDownloadOperation(requestId, authorizationData);
// Use TrackAsync to indicate that the application should wait to ensure that
// the download status is completed.
var bulkOperationStatus = await bulkDownloadOperation.TrackAsync(null, tokenSource.Token);
var resultFilePath = await bulkDownloadOperation.DownloadResultFileAsync(
FileDirectory,
ResultFileName,
decompress: true,
overwrite: true // Set this value true if you want to overwrite the same file.
);
Console.WriteLine(String.Format("Download result file: {0}", resultFilePath));
Console.WriteLine(String.Format("Status: {0}", bulkOperationStatus.Status));
Console.WriteLine(String.Format("TrackingId: {0}\n", bulkOperationStatus.TrackingId));
}
Progress<BulkOperationProgressInfo> progress = new Progress<BulkOperationProgressInfo>() {
@Override
public void report(BulkOperationProgressInfo value) {
System.out.println(value.getPercentComplete() + "% Complete\n");
}
};
java.lang.String requestId = RequestIdGoesHere;
BulkDownloadOperation bulkDownloadOperation = new BulkDownloadOperation(requestId, authorizationData);
// You may optionally cancel the trackAsync operation after a specified time interval.
BulkOperationStatus<DownloadStatus> downloadStatus = bulkDownloadOperation.trackAsync(
progress,
null
).get(3600000, TimeUnit.MILLISECONDS);
System.out.printf(
"Download Status:\nPercentComplete: %s\nResultFileUrl: %s\nStatus: %s\n",
downloadStatus.getPercentComplete(), downloadStatus.getResultFileUrl(), downloadStatus.getStatus()
);
File resultFile = bulkDownloadOperation.downloadResultFileAsync(
new File(FileDirectory),
ResultFileName,
true, // Set this value to true if you want to decompress the ZIP file
true, // Set this value true if you want to overwrite the same file.
null
).get();
System.out.println(String.format("Download result file: %s", resultFile.getName()));
System.out.println(String.format("Status: %s", downloadStatus.getStatus()));
System.out.println(String.format("TrackingId: %s\n", downloadStatus.getTrackingId()));
request_id = RequestIdGoesHere
bulk_download_operation = BulkDownloadOperation(
request_id = request_id,
authorization_data = authorization_data,
poll_interval_in_milliseconds = 5000,
environment = ENVIRONMENT
)
# Use track() to indicate that the application should wait to ensure that the download status is completed.
# You may optionally cancel the track() operation after a specified time interval.
bulk_operation_status = bulk_download_operation.track(timeout_in_milliseconds=3600000)
result_file_path = bulk_download_operation.download_result_file(
result_file_directory = FILE_DIRECTORY,
result_file_name = DOWNLOAD_FILE_NAME,
decompress = True,
overwrite = True, # Set this value true if you want to overwrite the same file.
timeout_in_milliseconds=3600000 # You may optionally cancel the download after a specified time interval.
)
print("Download result file: {0}\n".format(result_file))
print("Status: {0}\n".format(bulk_operation_status.status))
Consulta e Repetição
Consulte os resultados de transferência e carregamento em intervalos razoáveis. Conhece os seus dados melhor do que ninguém. Por exemplo, se transferir uma conta com menos de um milhão de palavras-chave, considere consultar em intervalos de 5 a 20 segundos. Se a conta contiver cerca de um milhão de palavras-chave, considere consultar em intervalos de um minuto após aguardar cinco minutos. Para contas com cerca de quatro milhões de palavras-chave, considere consultar em intervalos de um minuto após aguardar 10 minutos.
O BulkServiceManager consulta automaticamente o ficheiro de resultado em intervalos de 1000 milissegundos para as primeiras cinco tentativas e esse comportamento não é configurável. A propriedade StatusPollIntervalInMilliseconds determina o intervalo de tempo entre cada tentativa de consulta após as cinco tentativas iniciais. Para obter um exemplo, veja Conclusão em Segundo Plano acima. O valor predefinido é 5000, por isso, se não definir este valor, o BulkServiceManager irá consultar na seguinte sequência de minutos: 1, 2, 3, 4, 5, 10, 15, 20 e assim sucessivamente. Se definir este valor como 10000, o BulkServiceManager irá consultar na seguinte sequência: 1, 2, 3, 4, 5, 15, 25, 35 e assim sucessivamente. O intervalo mínimo de inquérito é 1000 e, se especificar um valor inferior a 1000, será emitida uma exceção.
O BulkServiceManager repetirá automaticamente as operações de carregamento, transferência e consulta até à duração máxima de tempo limite que definiu. Pode definir a duração máxima do tempo limite de repetição. Se não for especificado nenhum tempo limite, o BulkServiceManager continuará a tentar até que o servidor devolva um tempo limite ou um erro interno. Separadamente, se estiver a carregar ou a transferir ficheiros grandes, deve considerar definir as propriedades UploadHttpTimeout ou DownloadHttpTimeout .
Diretório de Trabalho e BulkServiceManager
Com os SDKs .NET e Java do Bing Ads, pode definir o diretório de trabalho onde o BulkServiceManager deve armazenar ficheiros temporários em massa. Por exemplo, quando transfere entidades com o SDK .NET de Anúncios do Bing, embora só trabalhe diretamente com objetos BulkEntity , um ficheiro em massa é transferido para o diretório de trabalho. Da mesma forma, quando carrega entidades, é escrito um ficheiro temporário no diretório de trabalho e, em seguida, carregado para o serviço em massa. O diretório temporário do sistema será utilizado se não for especificado outro diretório de trabalho.
Se estiver a utilizar um serviço alojado, como o Microsoft Azure, deverá garantir que não excede os limites do diretório temporário. Podem existir outros motivos para utilizar um diretório de trabalho personalizado. Pode especificar um diretório de trabalho diferente para cada instância do BulkServiceManager ao definir a propriedade WorkingDirectory . Também é responsável por criar e remover quaisquer diretórios. Depois de iterar as entidades em massa, pode limpar os ficheiros do diretório de trabalho.
Importante
O método CleanupTempFiles remove todos os ficheiros (mas não os subdiretórios) no diretório de trabalho, quer os ficheiros tenham ou não sido criados pela instância atual do BulkServiceManager .
public async Task RunAsync(AuthorizationData authorizationData)
{
var bulkServiceManager = new BulkServiceManager(authorizationData);
var progress = new Progress<BulkOperationProgressInfo>(x =>
Console.WriteLine(String.Format("{0} % Complete", x.PercentComplete.ToString(CultureInfo.InvariantCulture)))
);
var downloadParameters = new DownloadParameters
{
CampaignIds = null,
DataScope = DataScope.EntityData,
Entities = DownloadEntity.Keywords,
FileType = DownloadFileType.Csv,
LastSyncTimeInUTC = null,
ResultFileDirectory = FileDirectory,
ResultFileName = ResultFileName,
OverwriteResultFile = false // Set this value true if you want to overwrite the same file.
};
// The system temp directory will be used if another working directory is not specified. If you are
// using a hosted service such as Microsoft Azure you'll want to ensure you do not exceed the file or directory limits.
// You can specify a different working directory for each BulkServiceManager instance.
bulkServiceManager.WorkingDirectory = FileDirectory;
// The DownloadEntitiesAsync method returns IEnumerable<BulkEntity>, so the download file will not
// be accessible e.g. for CleanupTempFiles until you iterate over the result e.g. via ToList().
var resultEntities = (await bulkServiceManager.DownloadEntitiesAsync(
downloadParameters
)).ToList();
// The CleanupTempFiles method removes all files (but not sub-directories) within the working directory,
// whether or not the files were created by this BulkServiceManager instance.
bulkServiceManager.CleanupTempFiles();
}
BulkServiceManager bulkServiceManager = new BulkServiceManager(authorizationData);
Progress<BulkOperationProgressInfo> progress = new Progress<BulkOperationProgressInfo>() {
@Override
public void report(BulkOperationProgressInfo value) {
System.out.println(value.getPercentComplete() + "% Complete\n");
}
};
DownloadParameters downloadParameters = new DownloadParameters();
downloadParameters.setCampaignIds(null);
ArrayList<DataScope> dataScope = new ArrayList<DataScope>();
dataScope.add(DataScope.ENTITY_DATA);
downloadParameters.setDataScope(dataScope);
downloadParameters.setFileType(FileType);
downloadParameters.setLastSyncTimeInUTC(null);
ArrayList<DownloadEntity> bulkDownloadEntities = new ArrayList<DownloadEntity>();
bulkDownloadEntities.add(DownloadEntity.KEYWORDS);
downloadParameters.setEntities(bulkDownloadEntities);
downloadParameters.setResultFileDirectory(new File(FileDirectory));
downloadParameters.setResultFileName(ResultFileName);
downloadParameters.setOverwriteResultFile(true); // Set this value true if you want to overwrite the same file.
// The system temp directory will be used if another working directory is not specified. If you are
// using a cloud service such as Microsoft Azure you'll want to ensure you do not exceed the file or directory limits.
// You can specify a different working directory for each BulkServiceManager instance.
bulkServiceManager.setWorkingDirectory(new File(FileDirectory));
// The downloadEntitiesAsync method returns BulkEntityIterable, so the download file will not
// be accessible e.g. for cleanupTempFiles until you iterate over the result and close the BulkEntityIterable instance.
BulkEntityIterable tempEntities = bulkServiceManager.downloadEntitiesAsync(
downloadParameters,
null,
null
).get();
ArrayList<BulkEntity> resultEntities = new ArrayList<BulkEntity>();
for (BulkEntity entity : tempEntities) {
resultEntities.add(entity);
}
tempEntities.close();
// The cleanupTempFiles method removes all files (not sub-directories) within the working directory,
// whether or not the files were created by this BulkServiceManager instance.
bulkServiceManager.cleanupTempFiles();
See Also
Sandbox
Exemplos de Código da API de Anúncios do Bing
Endereços do Serviço Web da API de Anúncios do Bing
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários