Partilhar via

Transferência e Carregamento em Massa

  • Artigo

Com o serviço em massa , pode transferir e carregar as definições de campanha de forma assíncrona em segundo plano. O serviço em massa é recomendado para gerir dados em grande escala, especialmente se precisar de adicionar ou atualizar anúncios e palavras-chave em vários grupos de anúncios ou campanhas numa conta. Para algumas entidades, também pode transferir sugestões de oferta e dados de classificação de qualidade. Cada registo pode ser carregado com êxito, quer outros registos no mesmo ficheiro contenham ou não erros. Para obter informações sobre o esquema utilizado para o ficheiro de transferência e carregamento, incluindo detalhes sobre que entidades, sugestões de oferta e dados de classificação de qualidade estão disponíveis, veja Esquema de Ficheiros em Massa.

Importante

Podem ser adicionados novos tipos de registo (linhas) e campos (colunas) em qualquer altura e não deve depender da ordem dos registos ou campos no ficheiro de resultados de transferência em massa ou carregamento em massa. Da mesma forma, salvo indicação em contrário na documentação de referência, não deve depender de um conjunto fixo de valores devolvidos em cada campo.

Se estiver a utilizar uma linguagem .NET, Java ou Python, deve utilizar as Bibliotecas de Cliente da API de Anúncios do Bing. Os SDKs .NET, Java e Python abstraem os detalhes de baixo nível descritos abaixo. Por exemplo, em vez de chamar DownloadCampaignsByAccountIds e GetBulkDownloadStatus para transferir um ficheiro, pode utilizar um método com a classe BulkServiceManager . Para obter mais informações sobre como utilizar a transferência e o carregamento em massa com os SDKs, veja Bulk Service Manager.

Transferência em Massa

Para transferir os dados de campanha de uma conta, chame a operação DownloadCampaignsByAccountIds . Para transferir os dados de campanhas específicas, chame a operação DownloadCampaignsByCampaignIds .

Transferir um Ficheiro em Massa

Pode pedir todos os dados da campanha ou apenas os dados que foram alterados desde a última vez que transferiu os dados da campanha. Para qualquer uma das operações de transferência, segue-se uma descrição geral das definições de pedido e do fluxo de trabalho de transferência.

Importante

Tem de utilizar as mesmas credenciais de utilizador para a operação de pedido de transferência ( downloadCampaignsByAccountIds ou DownloadCampaignsByCampaignIds) e a operação de consulta GetBulkDownloadStatus .

  1. Defina o elemento DataScope do pedido e especifique se pretende incluir sugestões de oferta ou dados de classificação de qualidade, além dos dados da entidade. Para obter uma lista de valores possíveis, veja o conjunto de valores DataScope .

  2. Defina o elemento DownloadFileType do pedido para selecionar Csv ou Tsv para o formato do ficheiro de transferência.

    Nota

    O ficheiro Csv ou Tsv transferido será comprimido por ZIP ou GZIP consoante o CompressionType que especificou. ZIP é a predefinição se não tiver especificado CompressionType.

  3. Defina o elemento Entidades do pedido para incluir a sua campanha, grupo de anúncios, anúncios e entidades de palavras-chave. Opcionalmente, pode incluir entidades adicionais, como palavras-chave negativas e destinos na transferência. Para obter uma lista de entidades que pode pedir, veja o conjunto de valores DownloadEntity .

  4. Defina o elemento LastSyncTimeInUTC do pedido para o carimbo de data/hora da transferência anterior para pedir apenas as entidades que foram atualizadas ou eliminadas desde a última transferência.

    Nota

    Se esta for a primeira vez que está a pedir uma transferência para as entidades especificadas, defina o elemento LastSyncTimeInUTC do pedido como NULL para transferir todas as entidades disponíveis.

  5. Submeta o pedido de transferência com a operação DownloadCampaignsByAccountIds ou DownloadCampaignsByCampaignIds .

  6. O pedido de transferência devolve um identificador que transmite à operação GetBulkDownloadStatus . Chama a operação GetBulkDownloadStatus num ciclo até que a transferência seja concluída ou falhe. O período de tempo que a transferência demora a concluir depende de várias variáveis, como o número de campanhas que pediu e o número de pedidos que já se encontram na fila. Devido a estas variáveis, o intervalo de consulta que utiliza pode variar. Tem dois dias para transferir o ficheiro a partir do momento em que submete o pedido de transferência. Se não tiver transferido o ficheiro com êxito neste período, este será removido do site de transferência e terá de chamar uma das operações de transferência novamente.

  7. Quando a operação GetBulkDownloadStatus for concluída com êxito, devolve o URL do ficheiro de transferência. Utilize o URL para copiar o ficheiro de transferência localmente. O URL tem de ser utilizado no prazo de cinco minutos após a operação GetBulkDownloadStatus devolver um código de estado De êxito . Se não iniciar a transferência dentro deste período de tempo, terá de chamar GetBulkDownloadStatus novamente para obter um novo URL.

  8. O ficheiro de transferência é comprimido no formato zip, pelo que tem de deszipar o ficheiro para aceder aos dados. Para obter informações sobre o esquema utilizado para o ficheiro de transferência, veja Esquema de Ficheiro em Massa.

Transferir As Melhores Práticas

Adira às melhores práticas para garantir uma utilização justa para si e para todos os clientes do Microsoft Advertising.

Importante

Enquanto os limites exatos de transferência e carregamento simultâneos estão sujeitos a alterações, o número de pedidos pendentes que submeteu é limitado. Se observar o erro 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod, pode submeter novamente o pedido depois de aguardar até 15 minutos, consoante a frequência e o tamanho dos pedidos que submeteu. Para obter mais informações, veja Limitação da API em Massa.

  • Peça apenas as entidades de transferência em massa necessárias. Podem ser adicionados novos tipos de registo (linhas) e campos (colunas) em qualquer altura e não deve depender da ordem dos registos ou campos no ficheiro de resultados de transferência em massa ou carregamento em massa.

  • Efetue uma transferência completa apenas uma vez. A partir daí, efetue transferências delta. Defina LastSyncTimeInUTC como o carimbo de data/hora da última transferência. O ficheiro de transferência contém o carimbo de data/hora da transferência na coluna SyncTime do registo Conta . Não há qualquer vantagem em efetuar sempre uma transferência completa e diminui o desempenho de todas as pessoas, incluindo a sua.

  • Consulte as transferências em intervalos razoáveis. Conhece os seus dados melhor do que ninguém. Se transferir uma conta com menos de um milhão de palavras-chave, considere consultar com intervalos de 15 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.

  • Chame a operação DownloadCampaignsByCampaignIds se a conta contiver mais de quatro milhões de palavras-chave. A chamada da operação DownloadCampaignsByAccountIds com uma conta que contenha mais de quatro milhões de palavras-chave falhará.

  • Poderá querer incluir menos campanhas no seu pedido DownloadCampaignsByCampaignIds . A chamada da operação DownloadCampaignsByCampaignIds com uma conta que contenha mais de oito milhões de palavras-chave falhará. Os pedidos que especificam menos campanhas por chamada normalmente são concluídos mais cedo do que as chamadas que especificam o número máximo permitido.

Carregamento em Massa

Pode submeter o ficheiro de carregamento em massa com HTTP POST para um URL fornecido pelo serviço em massa.

Nota

O limite de tamanho do ficheiro para carregamento em produção é de 100 MB e até 4 milhões de linhas. Para Sandbox , o limite é de 20 000 linhas.

Para obter informações sobre o esquema que deve utilizar para o ficheiro de carregamento, veja Esquema de Ficheiro em Massa.

Carregar um Ficheiro em Massa

Segue-se uma descrição geral das definições de pedido e do fluxo de trabalho de carregamento.

Importante

Tem de utilizar as mesmas credenciais de utilizador em todo o fluxo de trabalho GetBulkUploadUrl, HTTP POST e GetBulkUploadStatus .

  1. Defina o elemento AccountId do pedido GetBulkUploadUrl para o identificador de conta correspondente aos dados que serão carregados.

  2. Defina o elemento ResponseMode do pedido GetBulkUploadUrl para especificar se o serviço deve devolver erros e os dados correspondentes ou apenas os erros no ficheiro de resultados. Para obter mais informações, veja ResponseMode.

  3. Utilize o UploadUrl devolvido com a resposta GetBulkUploadUrl para submeter o ficheiro de carregamento em massa com HTTP POST. O tipo de conteúdo tem de ser multipart/form-data. Os ficheiros UTF-8 têm de incluir a marca de ordem de bytes (BOM). O carregamento comprimido por ZIP deve conter um ficheiro formatado como Csv ou Tsv. O ficheiro ZIP tem de estar corretamente estruturado, incluindo o fim do registo de diretório central.

    Nota

    O cabeçalho de Autorização padrão HTTP não é utilizado. Para autenticar, tem de adicionar e definir os elementos de cabeçalho personalizados do Microsoft Advertising do cliente HTTP, incluindo os cabeçalhos DeveloperToken, CustomerId e CustomerAccountId . Também tem de definir as credenciais de utilizador através do elemento de cabeçalho AuthenticationToken . Para obter mais informações, veja Authentication with OAuth and Where to Use the API Credentials (Autenticação com OAuth e Onde Utilizar as Credenciais da API).

    Tem de utilizar as mesmas credenciais de utilizador em todo o fluxo de trabalho GetBulkUploadUrl, HTTP POST e GetBulkUploadStatus .

    Eis um exemplo.

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

  4. Verifique o código de estado da resposta HTTP. Se o código de estado de resposta HTTP for 200, o ficheiro foi recebido com êxito pelo Microsoft Advertising. Se o código de estado de resposta HTTP for 401, a autenticação falhou, por exemplo, AuthenticationToken ou DeveloperToken era inválido. Se o código de estado de resposta HTTP for 400, também deve verificar o fluxo de resposta dos Códigos de Erro da Operação da API de Anúncios do Bing , por exemplo, no intervalo de 3220 - 3227.

    Eis uma mensagem de resposta de erro de exemplo a indicar que o URL já tinha sido utilizado para carregar um ficheiro em massa.

    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. A resposta GetBulkUploadUrl também inclui um RequestId que transmite para a operação GetBulkUploadStatus . Enquanto o carregamento estiver pendente, pode chamar a operação GetBulkUploadStatus num ciclo até que o carregamento seja concluído ou falhe. Tem quinze minutos para transferir o ficheiro de resultados do carregamento a partir do momento em que submete o pedido de carregamento. Se não tiver transferido o ficheiro com êxito neste período, este será removido do site de transferência e poderá não ser obtido. Se perder esta janela de oportunidade, pode chamar uma das operações de transferência para obter os dados de entidade mais recentes.

  6. Quando a operação GetBulkUploadStatus for concluída com êxito, devolve o URL do ficheiro de resultados de carregamento. Utilize o URL para copiar o ficheiro de resultados localmente. O URL tem de ser utilizado dentro de quinze minutos após o tempo em que a operação GetBulkUploadStatus devolve a cadeia de resposta de estado Concluído . Se não iniciar a transferência dentro deste período de tempo, terá de chamar GetBulkUploadStatus novamente para obter um novo URL.

    Nota

    O formato do ficheiro de resultado de carregamento será Csv ou Tsv e corresponderá ao formato do ficheiro que submeteu para carregamento.

Carregar Melhores Práticas

Adira às melhores práticas para garantir uma utilização justa para si e para todos os clientes do Microsoft Advertising.

Importante

Enquanto os limites exatos de transferência e carregamento simultâneos estão sujeitos a alterações, o número de pedidos pendentes que submeteu é limitado. Se observar o erro 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod, pode submeter novamente o pedido depois de aguardar até 15 minutos, consoante a frequência e o tamanho dos pedidos que submeteu. Para obter mais informações, veja Limitação da API em Massa.

  • Os ficheiros grandes podem degradar o desempenho do carregamento. É opcional e recomendado que o ficheiro seja comprimido para carregamento. Se comprimido, tem de ser formatado como ZIP com a extensão correspondente. O limite de tamanho do ficheiro para carregamento em produção é de 100 MB e até 4 milhões de linhas. Para Sandbox , o limite é de 20 000 linhas. Se conseguir limitar os carregamentos simultâneos por cliente abaixo de 5 ou 6, considere dividir o ficheiro em vez de se aproximar do limite de tamanho do ficheiro.

  • Limite os carregamentos simultâneos para 5 ou 6 por cliente para carregar ficheiros em paralelo. Aguarde em cada thread até que o ficheiro anterior seja processado e, em seguida, pode reutilizar o thread para carregar outro ficheiro. Por exemplo, um thread pode carregar um ficheiro e, após o estado do carregamento estar Concluído, ConcluídoComErro ou Falha , esse thread pode carregar outro ficheiro.

  • Carregue apenas as entidades e campos que está a adicionar ou atualizar. Se for fornecido, os campos só de leitura, como sugestões de licitação e dados de classificação de qualidade, serão ignorados.

  • Carregue um tipo de entidade por ficheiro para maximizar o desempenho. Existem algumas exceções, por exemplo, ao criar novas campanhas, anúncios e palavras-chave, pode ser mais eficiente carregá-las juntamente com chaves de referência. Como outro exemplo, se estiver a atualizar apenas 10 campanhas, 500 anúncios e 800 palavras-chave, pode incluí-las num carregamento em vez de dividir carregamentos por tipo.

  • Considere se precisa de pedir erros e resultados (ResponseMode = ErrorsAndResults) no ficheiro de resultados de carregamento ou se os erros apenas (ResponseMode = ErrorsOnly) serão suficientes. Considere se deve ou não sincronizar os resultados com os seus dados locais. Por exemplo, se estiver a atualizar entidades, poderá apenas precisar de saber se ocorreram erros e, nesse caso, pode especificar ResponseMode = ErrorsOnly no pedido GetBulkUploadUrl . Se estiver a adicionar novas entidades, pode especificar ResponseMode = ErrorsAndResults no pedido GetBulkUploadUrl para receber os identificadores de entidade resultantes.

  • Para tentativas de repetição parciais, não carregue todo o ficheiro se apenas um subconjunto dos registos resultar em erros. Carregue apenas os registos que pretende repetir.

  • Não repita até que o estado do carregamento seja Concluído, ConcluídoComErro ou Com Falhas. Se, por acaso, o desempenho não corresponder às expectativas, aguarde pelo resultado mesmo assim.

  • Procure resultados de carregamento em intervalos razoáveis. Inicialmente, deve aguardar um minuto por cada 10 mil linhas carregadas. Após o tempo de espera inicial, considere consultar em intervalos de um minuto.

See Also

Referência do Serviço em Massa
Endereços do Serviço Web da API de Anúncios do Bing