Partilhar via

Migrar para a Versão 13

  • Artigo

Nota

Pôr-do-sol da API de Anúncios do Bing a partir de 31 de outubro de 2019.

As secções abaixo descrevem as alterações da API de Anúncios do Bing da versão 12 para a versão 13.

Autenticação para Todos os Serviços

O ponto final da plataforma de identidades da Microsoft para programadores está agora disponível. O ponto final da plataforma de identidades da Microsoft permite contas escolares ou profissionais do Azure AD e contas Microsoft pessoais (MSA), como hotmail.com, outlook.com e msn.com. O ponto final do Live Connect só permite a autenticação com contas pessoais.

Embora a migração do ponto final do Live Connect para o ponto final da plataforma de identidades da Microsoft seja independente da migração da versão 12 para a 13, compreendemos que muitos programadores gostariam de atualizar durante o mesmo sprint.

Importante

O ponto final do Live Connect já não é a abordagem recomendada para os utilizadores do Microsoft Advertising. Atualize para o ponto final da plataforma de identidades da Microsoft para garantir que a sua aplicação pode suportar todos os utilizadores sem atrito ou interrupção do serviço. Apenas o ponto final da plataforma de identidades da Microsoft (v2.0) lhe permite obter tokens de acesso para autenticar contas profissionais e pessoais através da API de Anúncios do Bing.

Informações do Ad

Para obter a documentação de referência de serviço abrangente da versão 13, veja Ad Insight.

Alterações Interruptivas

Cliente Proxy

Atualize o cliente proxy para utilizar o novo endereço de ponto final e espaço de nomes.

O espaço de nomes de destino é https://bingads.microsoft.com/AdInsight/v13.

O ponto final de produção é https://adinsight.api.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc.

O ponto final do sandbox é https://adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc.

Espaço de Nomes do Contrato de Dados

Anteriormente na versão 12, o espaço de nomes do contrato de dados para algumas entidades tinha variado do espaço de nomes de destino do Ad Insight. Se utilizou qualquer um dos seguintes espaços de nomes da versão 12, tem de utilizar https://bingads.microsoft.com/AdInsight/v13 a versão 13.

  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.SearchParameters
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.Common
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.Criterions
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity

Os clientes que codificam o envelope SOAP e.g. PHP clientes que codificam um SoapVar para DateRangeSearchParameter, terá de atualizar para o espaço de nomes de destino da Versão 13 do Ad Insight, ou seja, https://bingads.microsoft.com/AdInsight/v13.

Os clientes do SDK Python do Bing Ads terão de atualizar vários prefixos de espaço de nomes para os objetos de fábrica de cliente SUDS , por exemplo, se tiver utilizado ns4:DateRangeSearchParameter na Versão 12 da API de Anúncios do Bing, utilizará DateRangeSearchParameter (sem o prefixo 'ns4') na versão 13. Veja Utilizar SUDS para obter detalhes sobre como determinar o prefixo do espaço de nomes.

Em massa

Para obter a documentação de referência abrangente do serviço da versão 13, veja Bulk (Bulk).

Alterações Interruptivas

Cliente Proxy

Atualize o cliente proxy para utilizar o novo endereço de ponto final e espaço de nomes.

O espaço de nomes de destino é https://bingads.microsoft.com/CampaignManagement/v13.

O ponto final de produção é https://bulk.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc.

O ponto final do sandbox é https://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc.

Recursos de Imagem de Anúncios Reativos

O ID do Suporte de Dados da Imagem Horizontal, o ID do Suporte de Dados do Logótipo horizontal, o ID do Suporte de Dados da Imagem Quadrada e o ID do Suporte de Dados do Logótipo Quadrado são preteridos a partir do registo do AD Reativo . Estes continuarão visíveis no ficheiro de transferência, embora, uma vez que serão removidos numa versão futura, não deve assumir quaisquer dependências nestas colunas. Em alternativa, utilize a coluna Imagens .

Dados de Desempenho de Entidades

A transferência em massa de dados de desempenho era anteriormente desativada na versão 12. Agora, na versão 13, o valor EntityPerformanceData do conjunto de valores DataScope foi removido do contrato de serviço. Além disso, os objetos Date e PerformanceStatsDateRange e o conjunto de valores ReportTimePeriod são removidos Se pretender que os dados sejam agregados por dia, semana ou mês, pode utilizar a API de Relatórios. Para obter mais detalhes, veja Guias da API de Relatórios.

Gestão de Campanhas

Para obter a documentação de referência abrangente do serviço da versão 13, veja Gestão de Campanhas.

Alterações Interruptivas

Cliente Proxy

Atualize o cliente proxy para utilizar o novo endereço de ponto final e espaço de nomes.

O espaço de nomes de destino é https://bingads.microsoft.com/CampaignManagement/v13.

O ponto final de produção é https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc.

O ponto final do sandbox é https://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc.

Recursos de Imagem de Anúncios Reativos

Os elementos LandscapeImageMediaId, LandscapeLogoMediaId, SquareImageMediaId e SquareLogoMediaId são removidos do objeto ResponsiveAd . Em alternativa, tem de utilizar o elemento Imagens .

Recursos de Texto de Anúncios Reativos

Se utilizou o elemento de cadeia LongHeadline na versão 12, deve utilizar o elemento LongHeadlineString (cadeia) na versão 13. O tipo de dados de LongHeadline é atualizado de cadeia para AssetLink. Esta ligação de recursos está reservada para utilização futura.

As listas de ligações de ativos Cabeçalhos e Descrições são adicionadas para utilização futura.

Paginação Predefinida para GetMediaMetaDataByAccountId

Se o elemento PageInfo não estiver definido quando chamar a operação GetMediaMetaDataByAccountId , o Índice da página desfasamento será 0 e o Tamanho predefinido será 1000. Na versão 12, se PageInfo não estiver definido, todos os metadados multimédia na conta serão devolvidos.

Proposta de Critério Ignorada para Tipo de Dados Inválido

Para a versão 12 e 13 ao adicionar e atualizar um BiddableCampaignCriterion, os requisitos de tipo de objeto CriterionBid derivados variam consoante o contexto do tipo de objeto Critério derivado com o qual está emparelhado. Por exemplo, se o Critério herdado for um critério ProductScope , deve utilizar um objeto FixedBid (não um BidMultiplier).

Na versão 13, se não utilizar o objeto Critério correto, a oferta pedida será ignorada: se a oferta for necessária, a operação falhará; Se a oferta for opcional, será utilizada a oferta predefinida.

Na versão 12, se não utilizar o objeto Critério correto, a oferta pedida teria sido honrada; no entanto, quando obter o objeto mais tarde, é devolvido o tipo correto. Por outras palavras, o tipo de dados que definiu não é o mesmo que o tipo de dados obtido.

Esta alteração da versão 12 para a versão 13 aplica-se apenas aos critérios bidíveis ao nível da campanha. Para os critérios de grupo de anúncios bidíveis da versão 12 e 13, se não utilizar o objeto critério correto, a oferta pedida será ignorada: se a oferta for necessária, a operação falhará; Se a oferta for opcional, será utilizada a oferta predefinida.

Oferta de Palavra-chave Opcional

Quando chama a operação AddKeywords , o elemento Bid da Palavra-chave é opcional. Anteriormente na versão 12, a oferta era necessária para adicionar palavras-chave. Se pretender herdar a oferta de grupo de anúncios predefinida para a palavra-chave e o tipo de correspondência, pode deixar a oferta de palavra-chave vazia.

Tipo de Correspondência de Palavra-chave Negativa

O elemento MatchType da NegativeKeyword é nillable. Se anteriormente tinha assumido uma dependência do valor MatchType predefinido na versão 12, ou seja, Exato, tem de definir explicitamente este elemento necessário na versão 13.

Origem de Anúncios de Pesquisa Dinâmica

O elemento Origem do DynamicSearchAdsSetting é nillable. O elemento IncludeDynamicSearchAdsSource é removido das mensagens de pedido AddCampaigns e UpdateCampaigns . Se estiver ativado para feeds de página, na versão 13, pode definir a Origem.

Descrição da Campanha

O elemento Descrição é removido do objeto Campanha . Ainda pode utilizar o elemento Nome para fornecer um nome de campanha exclusivo.

Devolver Campos Adicionais

O elemento ReturnAdditionalFields é removido de GetAdExtensionsAssociations, GetAdExtensionsByIds, GetAdGroupCriterionsByIds, GetAdGroupsByCampaignId, GetAdGroupsByIds, GetAdsByAdGroupId, GetAdsByEditorialStatus, GetAdsByIds, GetCampaignsByAccountId, GetCampaignsByIds, GetKeywordsByAdGroupId, GetKeywordsByEditorialStatus e GetKeywordsByIds solicita mensagens. Todos os elementos de cada anúncio, extensão de anúncios, grupo de anúncios, critério de grupo de anúncios bidível, campanha e palavra-chave são devolvidos por predefinição.

Em paralelo, os conjuntos de valores AdAdditionalField, AdExtensionAdditionalField, AdGroupAdditionalField, AdGroupCriterionAdditionalField, CampaignAdditionalField e KeywordAdditionalField são removidos.

Migração de Destino Concluída

A migração de um destino partilhado para uma campanha exclusiva e critérios de destino do grupo de anúncios foi previamente concluída. O elemento IsMigrated foi removido da resposta das operações AddAdGroupCriterions, UpdateAdGroupCriterions, AddCampaignCriterions e UpdateCampaignCriterions .

Novas Funcionalidades

Novos Tipos de Estratégia de Oferta

Os tipos de estratégia de oferta MaxRoasBiddingScheme e TargetRoasBiddingScheme são adicionados para utilização futura na versão 13.

Partilha de Clientes

O elemento CustomerShare é adicionado aos objetos Audience e UetTag . Este elemento está reservado para utilização futura.

Exclusão do Objetivo de Conversão da Licitação

O elemento ExcludeFromBidding é adicionado ao objeto ConversionGoal . Este elemento está reservado para utilização futura.

Faturação do Cliente

Para obter a documentação de referência abrangente do serviço da versão 13, veja Faturação do Cliente.

Alterações Interruptivas

Cliente Proxy

Atualize o cliente proxy para utilizar o novo endereço de ponto final e espaço de nomes.

O espaço de nomes de destino é https://bingads.microsoft.com/Billing/v13.

O ponto final de produção é https://clientcenter.api.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc.

O ponto final do sandbox é https://clientcenter.api.sandbox.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc.

Objeto Ordem de Inserção

São adicionadas várias propriedades ao objeto InsertionOrder .

O elemento BalanceAmount é removido e substituído pelo elemento BudgetRemaining .

GetInsertionOrdersByAccount foi removido

A operação GetInsertionOrdersByAccount foi removida. Pode utilizar SearchInsertionOrders na versão 13.

Gestão de Clientes

Para obter a documentação de referência abrangente do serviço da versão 13, veja Gestão de Clientes.

Alterações Interruptivas

Cliente Proxy

Atualize o cliente proxy para utilizar o novo endereço de ponto final e espaço de nomes.

O espaço de nomes de destino é https://bingads.microsoft.com/Customer/v13.

O ponto final de produção é https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc.

O ponto final do sandbox é https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc.

São efetuadas várias alterações ao objeto ClientLink .

Endereço do Cliente

Na versão 13, o elemento CustomerAddress será incluído em todos os objetos de Cliente devolvidos por predefinição. Não precisa de pedir explicitamente este elemento. O elemento IncludeCustomerAddress é removido das mensagens de pedido GetCustomer e SearchCustomers .

IDs da Conta Associada

Na versão 13, o elemento LinkedAccountIds será incluído em todos os objetos CustomerRole devolvidos por predefinição. Não precisa de pedir explicitamente este elemento. O elemento IncludeLinkedAccountIds é removido da mensagem de pedido GetUser .

Informações Fiscais para a Austrália e o Brasil

As chaves TaxId e TaxType já não estão disponíveis quando define a TaxInformation da conta para a Austrália e o Brasil. Para a Austrália, utilize AUGSTNumber como a chave e defina o valor para o seu identificador fiscal. Para o Brasil, as chaves possíveis são CCM, CPF e CNPJ.

Descrição Versão 12 Versão 13
Contas na Austrália TaxId=YourTaxId AUGSTNumber=YourTaxId
Contas Comerciais no Brasil TaxId=YourTaxId; TaxType=Business CPNJ=YourTaxId
Contas Pessoais no Brasil TaxId=YourTaxId; TaxType=Pessoal CPF=YourTaxId

Para contas empresariais na cidade de São Paulo, o Brasil não há alteração à chave CCM entre as versões 12 e 13.

Novas Funcionalidades

Permissão de Ligação da Função de Cliente

O elemento CustomerLinkPermission é adicionado ao objeto CustomerRole . Este elemento está reservado para utilização futura.

Relatórios

Para obter a documentação de referência abrangente do serviço da versão 13, veja Relatórios.

Alterações Interruptivas

Cliente Proxy

Atualize o cliente proxy para utilizar o novo endereço de ponto final e espaço de nomes.

O espaço de nomes de destino é https://bingads.microsoft.com/Reporting/v13.

O ponto final de produção é https://reporting.api.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc.

O ponto final do sandbox é https://reporting.api.sandbox.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc.

Colunas Necessárias para ProductMatchCountReportRequest

As colunas necessárias são atualizadas ao submeter o ProductMatchCountReportRequest. Na versão 13, são necessárias as colunas AccountName, CampaignName, MatchedProductsAtProductGroup e ProductGroup.

Anteriormente na versão 12, além do requisito AccountName e CampaignName, era necessária uma ou mais das colunas de estatísticas de desempenho MatchedProductsAtAdGroup, MatchedProductsAtCampaign ou MatchedProductsAtProductGroup.

Filtro de Relatório de Idioma

O conjunto de valores LanguageReportFilter é adicionado. O elemento LanguageCode (cadeia) é substituído pelo elemento Languages (LanguageReportFilter) nos seguintes filtros de relatório.

Relatório Todas as Conversões e Receitas para Objetivos

As colunas Conversões e Receita nas colunas GoalsAndFunnelsReportColumn são renomeadas AllConversions e AllRevenue , respetivamente. O significado dos dados não foi alterado da versão 12 para a 13.

Cabeçalhos de Relatórios Franceses

O suporte para transferir um relatório com cabeçalhos em francês é removido. Apenas os cabeçalhos em inglês são suportados na versão 13. O elemento Language é removido do objeto ReportRequest e o conjunto de valores ReportLanguage é removido.

AgeGenderDemographicReportRequest removido

O AgeGenderDemographicReportRequest foi removido. Em vez disso, pode utilizar AgeGenderAudienceReportRequest.

Tipo de Campanha de Pesquisa

Para campanhas de Pesquisa, os dados devolvidos na coluna CampaignType são "Procurar". Na versão 12, o valor devolvido era "Procurar & conteúdo". A coluna CampaignType está disponível através dos conjuntos de valores AdGroupPerformanceReportColumn, AdPerformanceReportColumn, CampaignPerformanceReportColumn e SearchQueryPerformanceReportColumn .

Formato de Dados do Grupo de Produtos

O formato dos dados devolvidos na coluna ProductGroup é atualizado.

Versão Descrição Exemplos:
12 Utiliza "\" (barra para trás) para delimitar os níveis.

Os valores do atributo não estão entre "" (aspas duplas).

O nível de categoria é acrescentado aos valores do atributo, se aplicável, por exemplo, "(1º Nível)", "(2º Nível)", etc.		 * \ Category=Animals & Pet Supplies(1º Nível) \ Category=Pet Supplies(2º Nível) \ Category=Bird Supplies(3º Nível)
13 Utiliza "/" (barra) para delimitar os níveis.

Os valores dos atributos estão entre "" (aspas duplas).

Não indica o nível de categoria, por exemplo, "(1º Nível)" é removido.		 * / Category="Animals & Pet Supplies" / Category="Pet Supplies" / Category="Bird Supplies"

Esta alteração aplica-se à coluna ProductGroup através dos seguintes conjuntos de valores.

Travessão para Pontuação de Qualidade Indisponível

Na versão 13, se a classificação de qualidade não tiver sido calculada, os dados devolvidos serão "--" (traço duplo) nas colunas AdRelevance, ExpectedCtr, HistoricalAdRelevance, HistoricalExpectedCtr, HistoricalLandingPageExperience, HistoricalQualityScore, LandingPageExperience e QualityScore. Na versão 12, o valor de "0" (zero) tinha sido devolvido. Estas colunas estão disponíveis nos conjuntos de valores AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn, KeywordPerformanceReportColumn e ShareOfVoiceReportColumn .

Substituiu algumas colunas de partilha de impressão

As colunas ImpressionLostToAdRelevancePercent, ImpressionLostToBidPercent, ImpressionLostToExpectedCtrPercent, ImpressionLostToRelevancePercent e ImpressionLostToRankPercent são removidas dos conjuntos de valores AccountPerformanceReportColumn, AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn e ShareOfVoiceReportColumn .

Na versão 13, os dados que tinham sido divididos entre essas colunas da versão 12 são agregados e disponíveis através da coluna ImpressionLostToRankAggPercent, que tem em conta todos esses fatores ao calcular a impressão perdida para classificar a percentagem.

Colunas AverageCpp, ClickCalls e ManualCalls removidas

As colunas AverageCpp, ClickCalls e ManualCalls são removidas dos conjuntos de valores AccountPerformanceReportColumn, AdGroupPerformanceReportColumn e CampaignPerformanceReportColumn .

Colunas CallStatus e CallTypeName removidas

As colunas CallStatus e CallTypeName são removidas do conjunto de valores CallDetailReportColumn . O Microsoft Advertising deixou de cobrar chamadas manuais para um número controlado a 12 de março de 2014.

Exigir Âmbito de Conta, Campanha ou Grupo de Anúncios

Na versão 13, tem de definir o âmbito do pedido para contas, campanhas ou grupos de anúncios específicos. Por exemplo, pode incluir até 1000 contas, 300 campanhas ou 300 grupos de anúncios através de AccountThroughAdGroupReportScope. Anteriormente, na versão 12, poderia deixar o âmbito do relatório nulo para alguns tipos de relatório e os dados seriam devolvidos para todas as contas a que pudesse aceder.