Começar a usar o Python com a API Bing Ads

Para começar a desenvolver aplicativos da API do Bing Ads com Python, você pode começar com os exemplos fornecidos ou seguir um dos passo a passo do aplicativo para um aplicativo Web ou de Desktop .

Precisará de credenciais de utilizador com acesso ao Microsoft Advertising em produção ou sandbox. Para o ambiente de produção, você precisará de um token de desenvolvedor de produção. Todos os clientes de sandbox podem usar o token de desenvolvedor de sandbox universal, ou seja, BBD37VB98. Para obter mais informações, consulte Introdução à API e àSandbox do Bing Ads.

Para autenticar via OAuth, você também deve registrar um aplicativo e obter o identificador de cliente correspondente. Você também precisa tomar nota do segredo do cliente e redirecionar o URI se estiver desenvolvendo um aplicativo Web. Para obter mais detalhes sobre como registrar um aplicativo em produção e o fluxo de concessão de código de autorização, consulte Autenticação com OAuth e Autenticação com SDKs. Embora em produção você deva usar seu próprio ID de aplicativo (também conhecido como ID de cliente), todos os clientes do Microsoft Advertising podem usar o ID de cliente público "Aplicativo de amostra tutorial" em sandbox, ou seja, 00001111-aaaa-2222-bbbb-3333cccc4444. Para obter mais informações, consulte Sandbox.

Dependências

O SDK Python do Bing Ads suporta 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 no IDE ou no prompt de linha de comando.

pip.exe install msads

Para confirmar se o SDK Python do Bing Ads está instalado, execute o seguinte. Deverá ver msads (<versão>) na lista de saída.

pip.exe list

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

pip.exe install --upgrade msads

Instruções

Depois de instalar o SDK Python do Bing Ads, você pode baixar os exemplos do GitHub ou seguir um dos passo a passo do aplicativo para um Passo a passo: Aplicativo Web da API Bing Ads em Python ou Passo a passo: Aplicativo de Área de Trabalho da API Bing Ads no aplicativo Python .

Usando o SDK REST

O SDK Python do Bing Ads se comunica com a API REST do Microsoft Advertising usando classes de cliente geradas pelo OpenAPI apoiadas por modelos Pydantic . Você interage com a API por meio de uma instância ServiceClient , que lida com cabeçalhos de autenticação, roteamento de ponto de extremidade e envio de métodos automaticamente.

Configurando um ServiceClient

Crie um ServiceClient passando 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, BulkService, ReportingService, CustomerManagementService, CustomerBillingServicee AdInsightService.

Criar objetos

Importe classes de modelo diretamente e instancie-as com argumentos de openapi_client.models.campaign palavra-chave. Não há ArrayOf* tipos de wrapper — use listas Python simples sempre que um campo aceitar vários 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, instancie a subclasse concreta diretamente — nenhuma chamada de fábrica ou codificação especial é necessária. Parâmetros personalizados e outros objetos aninhados podem ser definidos em linha 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 do serviço de chamadas

Crie um objeto request e passe-o para o método correspondente no ServiceClient. Os métodos usam nomenclatura snake_case.

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 usa o cabeçalho HTTP padrão Authorization: Bearer <token> . O fluxo OAuth — concessão de código de autorização, manipulação de tokens de atualização e armazenamento de tokens — é idêntico ao SDK SOAP. Para obter detalhes, consulte Autenticação com os SDKs.

Gestão de erros

Os erros de serviço são gerados ApiException a openapi_client partir do pacote. A exceção expõe o código de status HTTP e o corpo da resposta de 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 em lote retornados no corpo da resposta, consulte Manipulando erros e exceções de serviço.

See Also

Bibliotecas de cliente da API Bing Ads
Exemplos de código da API Bing Ads
Endereços de serviço Web da API Bing Ads
Lidando com erros e exceções de serviço
Área restrita

  • Última atualização a