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

Artigo
05/01/2024

Importante

Recomendamos que utilize o Java 11 ou posterior. A versão mínima do Java que suportamos é a 1.8. Tem de exlude o CXF das suas dependências ao utilizar a versão 1.8. Pode criar este ficheiro de exemplo com o Maven.

Para começar a desenvolver aplicações da API de Anúncios do Bing com Java, 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 "Tutorial Sample App" público no sandbox, ou seja, 4c0b021c-00c3-4508-838f-d3127e8167ff. Para obter mais informações, consulte Sandbox.

Instalar o SDK

O SDK Java de Anúncios do Bing depende das bibliotecas listadas no Repositório Maven.

Quando cria um projeto maven e inclui o artefacto do Maven microsoft.bingads , conforme mostrado abaixo, as dependências adicionais são instaladas automaticamente. Se não estiver a utilizar um projeto maven, tem de incluir a versão correta de cada dependência. Para obter mais informações, veja as Instruções: Aplicação Web da API de Anúncios do Bing em Java ou Instruções: Aplicação de Ambiente de Trabalho da API de Anúncios do Bing em exemplos de aplicações Java.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>com.microsoft.bingads</groupId>
      <artifactId>microsoft.bingads</artifactId>
      <version>13.0.10</version>
    </dependency>
  </dependencies>
</project>

Nota

A versão 13.0.10 está incluída como exemplo. Para obter detalhes sobre a versão de dependência do SDK mais recente, veja o gitHub do SDK Java do Bing Ads README.md.

Instruções

Assim que tiver o SDK Java de Anúncios do Bing instalado, pode procurar os Exemplos de Código da API de Anúncios do Bing, transferir os exemplos do GitHub ou seguir uma das instruções da aplicação para uma aplicação Web ou de Ambiente de Trabalho .

Configurar o Sandbox

Para utilizar o ambiente do Sandbox , crie um novo ficheiro de texto com o nome bingads.properties no diretório de raiz de origem do projeto, por exemplo , ProjectName\src\bingads.properties e adicione o seguinte texto. Seguem-se os conteúdos completos do ficheiro bingads.properties . Se a definição do ambiente do sandbox tiver um formato incorreto ou estiver em falta, o ambiente predefinido será a produção.

environment=Sandbox

Também pode definir o ambiente para cada ServiceClient individualmente da seguinte forma.

CustomerService = new ServiceClient<ICustomerManagementService>(
    authorizationData,
    ApiEnvironment.SANDBOX,
    ICustomerManagementService.class
);

Quer defina o ambiente ServiceClient global ou individualmente, também terá de definir o ambiente OAuth como sandbox.

final OAuthDesktopMobileAuthCodeGrant oAuthDesktopMobileAuthCodeGrant = new OAuthDesktopMobileAuthCodeGrant(
    ClientId, 
    ApiEnvironment.SANDBOX
);

As aplicações Web com um segredo de cliente e o URI de redirecionamento personalizado devem utilizar OAuthWebAuthCodeGrant da seguinte forma.

OAuthWebAuthCodeGrant oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(
    ClientId, 
    ClientSecret, 
    new URL(RedirectUri),
    ApiEnvironment.SANDBOX
);

Registe os cabeçalhos de pedido e resposta na consola do . TrackingId está incluído nos cabeçalhos de resposta.

MessageHandler.getInstance().setTraceOn(true);

Personalizar o cliente HTTP

Para a maioria das aplicações, recomendamos que utilize a implementação predefinida do cliente HTTP no SDK Java de Anúncios do Bing, que depende do cliente JAX-RS do Apache CXF. Poderá querer personalizar o cliente HTTP para configurar algumas funcionalidades, como ativar a compressão, se utilizar uma implementação JAX-RS diferente, para alterar o tempo limite de HTTP, a configuração do proxy ou outras definições.

Para tal, pode criar um objeto personalizado HttpClientProvider e transmiti-lo para GlobalSettings.setHttpClientProvider() antes de efetuar chamadas de serviço. Por exemplo:

GlobalSettings.setHttpClientProvider(new HttpClientProvider() 
{ 
    @Override 
    protected ClientBuilder configureClientBuilder(ClientBuilder clientBuilder) { 
        return super.configureClientBuilder(clientBuilder) 
            // override default connect timeout 
            .connectTimeout(90, TimeUnit.SECONDS)
            // override default read timeout
            .readTimeout(5, TimeUnit.MINUTES) 
            // enable compression (if using Jersey client)
            .register(org.glassfish.jersey.message.GZipEncoder.class)
            .register(org.glassfish.jersey.client.filter.EncodingFilter.class);
    }
});

Chamadas do serviço de registo

Para ativar o registo para mensagens de pedido e resposta, pode definir a com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump propriedade como true:

System.setProperty("com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump", "true");

Por predefinição, o SDK Java de Anúncios do Bing utiliza o Apache CXF para fazer chamadas de serviço, que se baseia na Fachada de Registo Simples para Java para escrever os seus registos. Para enviar mensagens registadas para a consola do , pode adicionar a slf4j-simple implementação às dependências da aplicação. Por exemplo:

<dependency> 
    <groupId>org.slf4j</groupId> 
    <artifactId>slf4j-simple</artifactId> 
    <version>2.0.12</version> 
</dependency>

Partilhar via