Introdução à Utilização do Python com a API de Anúncios do Bing

Para começar a desenvolver aplicações da API de Anúncios do Bing com Python, pode começar com os exemplos fornecidos ou seguir uma das instruções da aplicação para uma aplicação Web ou de Ambiente de Trabalho .

Precisará de credenciais de utilizador com acesso ao Microsoft Advertising em produção ou sandbox. Para o ambiente de produção, precisará de um token de programador de produção. Todos os clientes do sandbox podem utilizar o token de programador de sandbox universal, ou seja, BBD37VB98. Para obter mais informações, veja Introdução à API de Anúncios do Bing e ao Sandbox.

Para autenticar através do OAuth, também tem de registar uma aplicação e obter o identificador de cliente correspondente. Também tem de tomar nota do segredo do cliente e redirecionar o URI se estiver a desenvolver uma aplicação Web. Para obter mais detalhes sobre como registar uma aplicação na produção e o fluxo de concessão de código de autorização, veja Authentication with OAuth and Authentication With the SDKs (Autenticação com OAuth e Autenticação com os SDKs). Apesar de, em produção, ter de utilizar o seu próprio ID de aplicação (também conhecido como ID de cliente), todos os clientes do Microsoft Advertising podem utilizar o ID de cliente público "Tutorial Sample App" no sandbox, ou seja, 00001111-aaaa-2222-bbbb-3333cccc4444. Para obter mais informações, consulte Sandbox.

Dependências

O SDK Python de Anúncios do Bing suporta o Python 3.8 ou superior. Deve instalar e executar uma das versões suportadas.

O SDK baseado em REST depende dos seguintes pacotes, que são instalados automaticamente:

Instalar o SDK

Para instalar o SDK Python do Bing Ads pela primeira vez, execute o seguinte a partir do IDE ou da linha de comandos.

pip.exe install msads

Para confirmar que o SDK python do Bing Ads está instalado, execute o seguinte. Deverá ver msads (<versão>) na lista de resultados.

pip.exe list

Se já tiver o SDK Python do Bing Ads instalado, pode executar este comando para obter os bits mais recentes.

pip.exe install --upgrade msads

Instruções

Assim que tiver o SDK Python do Bing Ads instalado, pode transferir os exemplos a partir do GitHub ou seguir uma das instruções da aplicação para uma Instruções: Aplicação Web da API de Anúncios do Bing em Python ou Instruções: Aplicação de Ambiente de Trabalho da API de Anúncios do Bing na aplicação Python .

Utilizar o SDK REST

O SDK Python de Anúncios do Bing comunica com a API REST de Publicidade da Microsoft através de classes de cliente geradas por OpenAPI apoiadas por modelos Pydantic . Interage com a API através de uma instância serviceClient , que processa cabeçalhos de autenticação, encaminhamento de pontos finais e distribuição de métodos automaticamente.

Configurar um ServiceClient

Crie um ServiceClient ao transmitir o nome do serviço, a versão da API, os dados de autorização e o ambiente de destino.

from bingads.service_client import ServiceClient

campaign_service = ServiceClient(
    service='CampaignManagementService',
    version=13,
    authorization_data=authorization_data,
    environment=ENVIRONMENT,  # 'production' or 'sandbox'
)

São suportados os seguintes nomes de serviço: CampaignManagementService, , BulkServiceReportingService, CustomerManagementService, CustomerBillingServicee AdInsightService.

Criar objetos

Importe classes de modelo diretamente de openapi_client.models.campaign e instancia-as com argumentos de palavra-chave. Não existem ArrayOf* tipos de wrapper — utilize listas python simples sempre que um campo aceite múltiplos itens.

from openapi_client.models.campaign import *

campaign = Campaign(
    name="Women's Shoes",
    daily_budget=50.0,
    budget_type=BudgetLimitType.DAILYBUDGETSTANDARD,
    time_zone='PacificTimeUSCanadaTijuana',
    languages=['All'],
)

Para tipos derivados, como ExpandedTextAd, instanciar diretamente a subclasse de betão – não são necessárias chamadas de fábrica ou codificação especial. Os parâmetros personalizados e outros objetos aninhados podem ser definidos inline através do construtor.

expanded_text_ad = ExpandedTextAd(
    title_part1='Contoso',
    title_part2='Quick & Easy Setup',
    title_part3='Seamless Integration',
    text='Find New Customers & Increase Sales!',
    text_part2='Start Advertising on Contoso Today.',
    path1='seattle',
    path2='shoe sale',
    # With FinalUrls you can separate the tracking template, custom parameters,
    # and landing page URLs.
    final_urls=['https://www.contoso.com/womenshoesale'],
    # Final Mobile URLs can also be used if you want to direct the user to a
    # different page for mobile devices.
    final_mobile_urls=['https://mobile.contoso.com/womenshoesale'],
    # Set custom parameters that are specific to this ad.
    url_custom_parameters=CustomParameters(
        parameters=[
            CustomParameter(key='promoCode', value='PROMO' + str(index)),
            CustomParameter(key='season', value='summer'),
        ]
    ),
)

ads = [expanded_text_ad]

Operações de serviço de chamadas

Crie um objeto de pedido e transmita-o para o método correspondente no ServiceClient. Os métodos utilizam snake_case nomenclatura.

add_request = AddCampaignsRequest(
    account_id=authorization_data.account_id,
    campaigns=[campaign],
)
response = campaign_service.add_campaigns(add_campaigns_request=add_request)
campaign_id = response.campaign_ids[0]

Autenticação

O SDK REST utiliza o cabeçalho HTTP padrão Authorization: Bearer <token> . O fluxo OAuth ( concessão de código de autorização, processamento de tokens de atualização e armazenamento de tokens) é idêntico ao SDK SOAP. Para obter detalhes, veja Authentication With the SDKs (Autenticação com os SDKs).

Processamento de erros

Os erros de serviço são gerados ApiException a partir do openapi_client pacote. A exceção expõe o código de estado HTTP e o corpo da resposta do erro.

from openapi_client.exceptions import ApiException

try:
    response = campaign_service.GetCampaignsByAccountId(
        AccountId=authorization_data.account_id,
        CampaignType='Search'
    )
except ApiException as ex:
    print(f"HTTP status {ex.status}: {ex.body}")

Para obter informações sobre como analisar erros de lote devolvidos no corpo da resposta, veja Handling Service Errors and Exceptions (Processar Erros e Exceções do Serviço).

See Also

Bibliotecas de Cliente da API de Anúncios do Bing
Exemplos de Código da API de Anúncios do Bing
Endereços do Serviço Web da API de Anúncios do Bing
Processamento de Erros e Exceções do Serviço
Sandbox

  • Last updated on