Começar a usar a API Ads Data Hub

Neste guia, explicamos como começar a criar aplicativos que usam a API REST do Ads Data Hub para interagir com o ADH. Com essa API, você tem acesso aos clientes do Ads Data Hub associados à sua Conta do Google e pode criar/executar consultas.

Configuração

Você precisa seguir algumas etapas antes de usar a API Ads Data Hub:

Verifique se o usuário que ativou a API recebeu a permissão serviceusage.services.enable no projeto do Google Cloud. O usuário com permissão serviceusage.services.enable também precisa estar na lista para acessar a API.
Ative a API Ads Data Hub no projeto do Google Cloud em que as credenciais do cliente ou a conta de serviço foram criadas. Para ativar a API Ads Data Hub em um projeto usando o console:
1. Acesse a biblioteca de APIs do console do Cloud.
2. Selecione o projeto que você quer usar na lista.
3. Pesquise "API Ads Data Hub".
4. Na página da API, clique em ATIVAR.
Gerencie as permissões:
1. A conta de serviço ou o endereço de e-mail usado para criar as credenciais precisa ser adicionado ao Ads Data Hub com as permissões apropriadas. Para a conta de serviço, é o endereço de e-mail dela. Para OAuth, é o endereço de e-mail do usuário. Assim, a conta de serviço ou a conta do usuário final tem permissão para executar consultas no Ads Data Hub.
(Recomendado) Instale uma biblioteca de cliente das APIs do Google:
1. As bibliotecas de cliente das APIs do Google estão disponíveis em várias linguagens conhecidas e permitem que você trabalhe com muitas APIs do Google. Embora não seja obrigatório, as bibliotecas reduzem a quantidade de código que você precisa escrever e simplificam a configuração da autenticação.

Biblioteca de cliente	Exemplos do Ads Data Hub
Biblioteca de cliente das APIs do Google para Java	Java
Biblioteca de cliente das APIs do Google para Python

Autenticar e autorizar

A API Ads Data Hub pode acessar e alterar dados na sua conta de cliente do Ads Data Hub. Portanto, ela precisa verificar se você é um usuário autorizado. Antes de usar a API, é preciso seguir um fluxo de autorização, que fornece as permissões necessárias para interagir com ela. É possível autenticar usando o OAuth 2.0 ou uma conta de serviço.

Configuração do OAuth 2.0

A API oferece suporte aos fluxos de trabalho de aplicativos instalados e da Web. Neste exemplo, vamos seguir apenas o fluxo de apps instalados.

Acesse o Console de APIs do Google e navegue até seu projeto de administrador.
Verifique se a API Ads Data Hub está ativada para seu projeto.
1. Se não estiver, clique em "+ Ativar APIs e serviços".
No menu de navegação à esquerda, clique em "Credenciais".
Abra o menu suspenso "Criar credenciais" e selecione "ID do cliente OAuth". Na página seguinte:
1. Selecione "Outro".
2. Você também pode dar um nome ao cliente.
3. Clique em "Criar".
Clique no ícone de download ao lado das credenciais que você acabou de criar.

Receber sua chave de API

Sua chave de API, também conhecida como chave de desenvolvedor, é usada para autenticação no exemplo de código Python abaixo. Para conseguir a chave de API:

Acesse a página "Credenciais" no Console de APIs
Verifique se o projeto do administrador está selecionado no menu suspenso no painel de navegação de cima.
Clique no ícone de download ao lado da chave de API.

Enviar um exemplo de solicitação

Python

"""This sample shows how to retrieve all accounts associated with the user.

For the program to execute successfully, ensure that you run it using Python 3.
"""
import json
from google_auth_oauthlib import flow
from googleapiclient.discovery import build

appflow = flow.InstalledAppFlow.from_client_secrets_file(
    # Replace client_secrets.json with your own client secret file.
    'client_secrets.json',
    scopes=['https://www.googleapis.com/auth/adsdatahub'])
appflow.run_local_server()
credentials = appflow.credentials
developer_key = input('Developer key: ').strip()
# For versions of the Google API Python client library prior to 2.0, the
# `static_discovery` parameter below should be removed.
service = build('AdsDataHub', 'v1', credentials=credentials,
                developerKey=developer_key, static_discovery=False)


def pprint(x):
  print(json.dumps(x, sort_keys=True, indent=4))


adh_account_id = input('ADH account ID (e.g. "customers/123456789"): ').strip()
pprint(service.customers().analysisQueries().list(parent
                                                  =adh_account_id).execute())

Java

/*
 * Copyright (c) 2019 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.adsdatahub.cmdline;

import com.google.api.services.adsdatahub.v1.AdsDataHub;
import com.google.api.services.adsdatahub.v1.model.Customer;
import com.google.api.services.adsdatahub.v1.model.ListCustomersResponse;
import java.io.IOException;
import java.util.List;

/**
 * This sample illustrates how to retrieve all accounts associated to the user.
 *
 * <p>See the <a href="customers.list reference
 * documentation">https://developers.google.com/ads-data-hub/reference/rest/v1/customers/list</a>
 * for more details.
 */
public class ListCustomers extends BaseSample {

  @Override
  public String getName() {
    return "List customers";
  }

  @Override
  public String getDescription() {
    return "Lists customers associated with the authorized user";
  }

  @Override
  public void execute(AdsDataHub client) throws IOException {
    String pageToken = null;
    boolean noData = true;

    System.out.println("========================================");
    System.out.printf("Listing of customers associated with the authorized user:\n");
    System.out.println("========================================");

    do {
      ListCustomersResponse response = client.customers().list().setPageToken(pageToken).execute();
      pageToken = response.getNextPageToken();
      List<Customer> customers = response.getCustomers();

      if (customers != null && customers.size() > 0) {
        noData = false;
        for (Customer customer : customers) {
          System.out.printf("* Customer id: %d\n", customer.getCustomerId());
          System.out.printf("\tCustomer name: %s\n", customer.getDisplayName());
        }
      }
    } while (pageToken != null);

    if (noData) {
      System.out.println("No customers were found associated with the authorized user.");
    }
  }
}

Próximas etapas

Confira exemplos de consultas no Ads Data Hub que você pode criar e executar com a API REST do Ads Data Hub.
Faça testes com os exemplos para conhecer melhor a API e personalizar como quiser. Depois:
- Confira o status da operação de consulta.
- Use uma biblioteca de cliente do BigQuery para recuperar os resultados completos da consulta.
Se tiver dúvidas ou feedback sobre a API, procure o suporte do ADH.

Configurar sua conta

Avançar

Usar a interface da Web

Começar a usar a API Ads Data Hub Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.