Protocolo dos Serviços de API de Anúncios do Bing

Pode escrever a sua aplicação API de Anúncios do Bing em qualquer idioma que suporte serviços Web. Um documento WSDL (web services description language) é definido para cada serviço Web. O WSDL define as operações que um serviço Web oferece e o formato das mensagens de pedido e resposta que o cliente envia e recebe das operações. As mensagens de pedido e resposta definem os nomes e tipos dos dados que o cliente troca com a operação. Para obter mais informações sobre WSDLs, veja a especificação W3C WSDL.

SOAP para a API de Anúncios do Bing

A API de Anúncios do Bing suporta o Protocolo SOAP (Simple Object Access Protocol). Algumas linguagens, como C# e Java, fornecem ferramentas que geram classes de proxy a partir do WSDL. Se o seu idioma de eleição não fornecer uma ferramenta para gerar classes de proxy, terá de gerar as suas próprias classes de proxy ou envelopes SOAP. Para gerar as classes de proxy, precisa do endereço Web do documento WSDL do serviço que pretende utilizar. Cada um dos ambientes de sandbox e produção do Microsoft Advertising tem um endereço exclusivo. Os endereços também incluem o número da versão do WSDL específico de uma versão principal da API de Anúncios do Bing. Para WSDLs de serviço de produção e sandbox da versão mais recente da API de Anúncios do Bing, veja Endereços do Serviço Web da API de Anúncios do Bing.

Ordem do Elemento SOAP XML

Quando cria uma mensagem de pedido SOAP, a ordem dos elementos no corpo SOAP é crítica. Os elementos têm de estar na mesma ordem definida na linguagem de descrição (WSDL) dos serviços Web. Se os elementos necessários estiverem fora de ordem, a chamada falhará. Se os elementos opcionais estiverem fora de ordem, a chamada poderá falhar ou os elementos serão ignorados. A sintaxe WSDL, que mostra a ordem correta dos elementos, está incluída em cada mensagem de pedido, mensagem de resposta e objeto de dados documentados no conteúdo de referência. Além disso, cada mensagem de pedido e resposta mostra um envelope SOAP de exemplo.

Nota

O XML é sensível às maiúsculas e minúsculas. Tem de utilizar o caso correto para os nomes dos valores. Linguagens de programação com tipos fortes, como C#, garantem que tem o caso correto antes de poder compilar. Outros idiomas poderão não lhe apresentar um erro de compilação se o caso correto não for utilizado; no entanto, o código falha no tempo de execução.

Êxito Parcial

A API de Anúncios do Bing suporta conclusões parciais para operações de adição, atualização e eliminação; Se um dos objetos na lista de objetos que está a adicionar, a atualização ou a eliminação falhar, a operação poderá ser bem-sucedida para outras pessoas na coleção. Quando chama uma operação Get que utiliza uma lista de identificadores, por exemplo, a operação GetKeywordsByIds e um dos identificadores na lista não é válido, a operação será bem-sucedida e o elemento de resposta que corresponde ao identificador de pedido inválido será nulo.

Atualização Parcial

Atualização Parcial da Gestão de Campanhas

A atualização parcial é suportada para a maioria, mas nem todos os objetos de dados de gestão de campanhas. Por exemplo, ao atualizar a propriedade Text de um ExpandedTextAd , só precisa de especificar os elementos ID e Texto . Os elementos só de leitura, como o estado editorial do anúncio, têm de ser deixados nulos ou vazios. Salvo indicação em contrário, os elementos opcionais podem ficar vazios e as definições existentes permanecem inalteradas.

A atualização parcial não é suportada para extensões de anúncios. Quaisquer elementos opcionais que não sejam enviados com o pedido de atualização serão eliminados da respetiva extensão de anúncio.

Atualização Parcial da Gestão de Clientes

O serviço de gestão de clientes efetua uma atualização completa das entidades, pelo que, para além das propriedades necessárias documentadas, tem de fornecer valores para todas as propriedades opcionais que não pretende que sejam nulas ou vazias.

Nota

Uma exceção a esta regra é o elemento ForwardCompatibilityMap de qualquer objeto. Por exemplo, se não fornecer o elemento ForwardCompatibilityMap da AdvertiserAccount, o serviço não atualizará nem anulará quaisquer propriedades que, de outra forma, teriam sido representadas por pares chave e valor.

Armazenar os Identificadores de Entidade Localmente

Deve manter um arquivo local da sua conta e entidades de campanha. Especificamente, deve armazenar localmente os identificadores das suas contas, clientes, campanhas, grupos de anúncios e palavras-chave. A maioria das chamadas requer o identificador da entidade. Se armazenar o identificador, elimina a chamada necessária para obter o identificador.

Por exemplo, muitas das chamadas de gestão de campanhas requerem um identificador de conta. Para obter o identificador da conta, pode utilizar o serviço de gestão de clientes. No entanto, em vez de chamar repetidamente o serviço, armazene o identificador da conta localmente, para que possa utilizá-lo em chamadas subsequentes.

Gerir a Sobrecarga Associada à Realização de Chamadas de Serviço Web

Seguem-se os custos gerais, no tempo de processamento, que estão associados a cada chamada de serviço Web.

• Estabelecer uma ligação HTTPS ao serviço Web.
• Autenticar o nome de utilizador e a palavra-passe.
• Validar o token de programador.

Estes custos ocorrem quer processe um único item ou um conjunto de itens. Para minimizar a sobrecarga, em geral, deve tentar processar o maior número possível de itens numa chamada. Por exemplo, em vez de chamar UpdateCampaigns para cada campanha que pretende atualizar, chame-a apenas uma vez para múltiplas campanhas que pretende atualizar. 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, deve utilizar o Serviço em massa. O Serviço em massa permite-lhe transferir dados como um ficheiro TSV ou CSV, modificá-lo conforme necessário e, em seguida, carregar as alterações. Para obter mais informações sobre como utilizar o Serviço em massa, veja Transferência e Carregamento em Massa.

Devido aos custos associados ao estabelecimento de uma ligação a um serviço Web, deve manter a ligação durante o tempo que for necessário. Por exemplo, se precisar de pedir vários relatórios, utilize o mesmo objeto de cliente do serviço de relatórios para todas as chamadas da operação do serviço de relatórios. Feche explicitamente a ligação quando já não precisar do serviço.

Alça de Limitação

A limitação da utilização de volumes extremamente elevados mantém uma utilização justa para todos os clientes do Microsoft Advertising.

Ad Insight API

Para o serviço Ad Insight, a limitação limita o número de chamadas à API que qualquer utilizador pode fazer dentro de um minuto.

Ao nível do cliente, o número de chamadas que um cliente pode fazer aos dados do cliente é restringido através de um protocolo deslizante com uma janela de 60 segundos.

Se exceder o limite de chamadas de serviço, verá o seguinte erro:

• Código de Erro Numérico: 117
• Código de Erro Simbólico: CallRateExceeded
• Mensagem: Excedeu o número de chamadas que pode efetuar num minuto. Reduza o número de chamadas efetuadas por minuto.

Quando observar este erro, pode submeter novamente o pedido abaixo do limite após aguardar 60 segundos.

API em Massa

O serviço em massa limita o número de pedidos que pode fazer para DownloadCampaignsByAccountIds, DownloadCampaignsByCampaignIds e GetBulkUploadUrl. Os detalhes dos limites de serviço são internos e estão sujeitos a alterações.

Se atingir o limite de chamadas de serviço, verá o seguinte erro:

• Código de Erro Numérico: 4204
• Código de Erro Simbólico: BulkServiceNoMoreCallsPermittedForTheTimePeriod
• Mensagem: Não serão permitidas mais chamadas de carregamento ou transferência em massa para esta conta durante o período de tempo atual. Se tiver atingido o limite de carregamento em massa, as operações de transferência em massa poderão ainda estar disponíveis ou vice-versa.

Se observar este erro, pode submeter novamente o pedido depois de aguardar até 15 minutos. Para obter mais detalhes, veja Melhores Práticas de Transferência em Massa e Melhores Práticas de Carregamento em Massa.

Tenha também em atenção que o limite de tamanho por ficheiro para carregamento em massa na produção é de 100 MB e até 4 milhões de linhas. Para Sandbox , o limite é de 20 000 linhas.

API de Gestão de Campanhas

Para o serviço Gestão de Campanhas, a limitação limita o número de chamadas à API que qualquer utilizador pode fazer dentro de um minuto.

Ao nível do cliente, o número de chamadas que um cliente pode fazer aos dados do cliente é restringido através de um protocolo deslizante com uma janela de 60 segundos.

Se atingir o limite de chamadas de serviço, verá o seguinte erro:

• Código de Erro Numérico: 117
• Código de Erro Simbólico: CallRateExceeded
• Mensagem: Excedeu o número de chamadas que pode efetuar num minuto. Reduza o número de chamadas efetuadas por minuto.

Quando observar este erro, pode submeter novamente o pedido abaixo do limite após aguardar 60 segundos.

API de Relatórios

O serviço Relatórios limita o número de pedidos que pode fazer a SubmitGenerateReportRequest. Os detalhes dos limites de serviço são internos e estão sujeitos a alterações.

Se atingir o limite de chamadas de serviço, verá o seguinte erro:

• Código de Erro Numérico: 207
• Código de Erro Simbólico: ConcurrentRequestOverLimit
• Mensagem: Já atingiu o número máximo de pedidos de relatório simultâneos. Aguarde até que os relatórios anteriores estejam concluídos e, em seguida, tente submeter um novo pedido.

Se observar este erro, aguarde até que os relatórios anteriores sejam concluídos e, em seguida, tente submeter um novo pedido.

See Also

Endereços do Serviço Web da API de Anúncios do Bing
Descrição Geral da API de Anúncios do Bing