Primeiros passos

A API de relatórios e tráfego do DCM/DFA oferece acesso programático às informações da sua conta do Campaign Manager. Ela é usada para gerenciar e criar campanhas e relatórios da mesma forma que isso é feito nos serviços da Web do Campaign Manager e do Criador de relatórios.

Este guia descreve como dar os primeiros passos com a API de relatórios e tráfego do DCM/DFA.

Pré-requisitos

Antes de usar a API de relatórios e tráfego do DCM/DFA, é preciso atender a alguns pré-requisitos:

  1. É necessário ter uma conta do Campaign Manager. Acesse Anunciantes/agências para ver informações de inscrição.
  2. Sua conta do Campaign Manager precisa ter o acesso à API ativado. Na maioria das contas, ele é ativado por padrão. Se você não tiver certeza, entre em contato com o representante da DoubleClick ou com a equipe de suporte do Campaign Manager para receber ajuda.
  3. Você precisa ter um perfil de usuário com acesso à conta. Peça que o administrador da conta do Campaign Manager crie um perfil de usuário associado a ela.
  4. Verifique as permissões de perfil de usuário na IU do Campaign Manager. Elas controlam o que o perfil pode acessar a partir da API. Não há permissões específicas à API.

Criar um projeto

Para começar a usar a API de relatórios e tráfego do DCM/DFA, primeiro é preciso criar ou selecionar um projeto no Console de APIs do Google e ativar a API. Esse link mostra as etapas do processo e ativa automaticamente a API de relatórios e tráfego do DCM/DFA.

Gerar credenciais

Todas as solicitações para a API de relatórios e tráfego do DCM/DFA precisam ser autorizadas. Para uma visão geral, leia como autorizar e identificar seu aplicativo no Google.

As instruções a seguir indicam o processo de criação de um ID do cliente OAuth 2.0 para usar com o fluxo de aplicativos instalados. Veja como gerar credenciais para o fluxo da conta de serviço no guia relacionado.

  1. Siga as etapas para configurar um projeto do Console de APIs do Google.
  2. Abra a página Credenciais no Console de APIs.
  3. Clique em Criar credenciais > ID do cliente OAuth.
  4. Selecione Outro quando for solicitado a escolher um tipo de aplicativo e insira as informações adicionais necessárias.
    • Se essa for a primeira vez que você cria um ID do cliente, além de selecionar o tipo de aplicativo, será possível configurar sua tela de consentimento clicando no botão Configurar tela de consentimento. Você não receberá uma solicitação para configurar sua tela de consentimento novamente depois de fazer isso pela primeira vez, mas essas informações poderão ser atualizadas a qualquer momento.
  5. Clique em Criar.

Quando terminar, você receberá um ID do cliente OAuth 2.0 e uma chave secreta do cliente. Será possível fazer download da chave no formato JSON e salvar para uso posterior.

Instalar uma biblioteca de cliente

A API de relatórios e tráfego do DCM/DFA é criada com base em HTTP e JSON. Assim, qualquer cliente HTTP padrão pode enviar solicitações a ela e analisar as respostas.

No entanto, as bibliotecas de cliente da API do Google proporcionam mais segurança, melhor integração de linguagens e compatibilidade para fazer solicitações autorizadas. As bibliotecas de cliente estão disponíveis em várias linguagens de programação. Ao usá-las, não é preciso configurar as solicitações HTTP nem analisar as respostas manualmente.

Para começar, selecione a linguagem de programação que você usa para o desenvolvimento.

C#

Instale a versão mais recente da biblioteca de cliente da API de relatórios e tráfego do DCM/DFA para .NET. Recomendamos usar o NuGet (em inglês) para gerenciar a instalação.

Abra o NuGet Package Manager Console e execute o seguinte comando:

Install-Package Google.Apis.Dfareporting.v3_2

Saiba mais

Java

Instale a versão mais recente da biblioteca de cliente da API de relatórios e tráfego do DCM/DFA para Java. Use o Maven (em inglês) para gerenciar a instalação.

Adicione a seguinte dependência ao arquivo pom.xml:

    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-dfareporting</artifactId>
      <version>v3.2-rev1-1.24.1</version>
      <exclusions>
        <exclusion>
          <groupId>com.google.guava</groupId>
          <artifactId>guava-jdk5</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

Saiba mais

PHP

Instale a versão mais recente da biblioteca de cliente da API de relatórios e tráfego do DCM/DFA para PHP. Recomendamos usar o Composer (em inglês) para gerenciar a instalação.

Abra um terminal e execute o seguinte comando:

composer require google/apiclient

Use esta opção se você já tiver instalado a biblioteca e quiser atualizá-la para a versão mais recente:

composer update google/apiclient

Dependendo do sistema, você precisará incluir sudo no início desses comandos.

Saiba mais

Python

Instale a versão mais recente da biblioteca de cliente da API de relatórios e tráfego do DCM/DFA para Python. Recomendamos usar o pip (em inglês) para gerenciar a instalação.

Abra um terminal e execute o seguinte comando:

pip install --upgrade google-api-python-client

Dependendo do sistema, você precisará incluir sudo no início desses comandos.

Saiba mais

Ruby

Instale a versão mais recente da biblioteca de cliente da API de relatórios e tráfego do DCM/DFA para Ruby. Recomendamos usar o RubyGems (em inglês) para gerenciar a instalação.

Abra um terminal e execute o seguinte comando:

gem install google-api-client

Use esta opção se você já tiver instalado a biblioteca e quiser atualizá-la para a versão mais recente:

gem update -y google-api-client

Dependendo do sistema, você precisará incluir sudo no início desses comandos.

Saiba mais

Veja mais linguagens compatíveis na página de bibliotecas de cliente.

Fazer uma solicitação

Depois de criar as credenciais OAuth 2.0 e instalar uma biblioteca de cliente, você estará pronto para usar a API de relatórios e tráfego do DCM/DFA. Veja o guia de início rápido abaixo e saiba como autorizar e configurar o cliente e fazer a primeira solicitação.

C#

  1. Carregue o arquivo da chave secreta do cliente e gere credenciais de autorização.

    Na primeira vez que fizer isso, será solicitado que você aceite uma mensagem de autorização no navegador. Antes de aceitar, verifique se você fez login usando uma Conta do Google com acesso ao Campaign Manager. Seu aplicativo será autorizado a acessar dados em nome de qualquer conta que estiver conectada no momento.

    // Load client secrets from the specified JSON file.
    GoogleClientSecrets clientSecrets;
    using(Stream json = new FileStream(pathToJsonFile, FileMode.Open, FileAccess.Read)) {
      clientSecrets = GoogleClientSecrets.Load(json);
    }
    
    // Create an asynchronous authorization task.
    //
    // Note: providing a data store allows auth credentials to be cached, so they survive multiple
    // runs of the application. This avoids prompting the user for authorization every time the
    // access token expires, by remembering the refresh token. The "user" value is used to
    // identify a specific set of credentials within the data store. You may provide different
    // values here to persist credentials for multiple users to the same data store.
    Task<UserCredential> authorizationTask = GoogleWebAuthorizationBroker.AuthorizeAsync(
        clientSecrets.Secrets,
        OAuthScopes,
        "user",
        CancellationToken.None,
        dataStore);
    
    // Authorize and persist credentials to the data store.
    UserCredential credential = authorizationTask.Result;
    
  2. Crie um cliente Dfareporting autorizado.

    // Create a Dfareporting service object.
    //
    // Note: application name should be replaced with a value that identifies your application.
    service = new DfareportingService(
        new BaseClientService.Initializer {
          HttpClientInitializer = credential,
          ApplicationName = "C# installed app sample"
        }
    );
    
  3. Realize uma operação.

    // Retrieve and print all user profiles for the current authorized user.
    UserProfileList profiles = service.UserProfiles.List().Execute();
    
    foreach (UserProfile profile in profiles.Items) {
      Console.WriteLine("Found user profile with ID {0} and name \"{1}\".",
          profile.ProfileId, profile.UserName);
    }
    

Java

  1. Carregue o arquivo da chave secreta do cliente e gere credenciais de autorização.

    Na primeira vez que fizer isso, será solicitado que você aceite uma mensagem de autorização no navegador. Antes de aceitar, verifique se você fez login usando uma Conta do Google com acesso ao Campaign Manager. Seu aplicativo será autorizado a acessar dados em nome de qualquer conta que estiver conectada no momento.

    // Load the client secrets JSON file.
    GoogleClientSecrets clientSecrets =
        GoogleClientSecrets.load(
            jsonFactory, Files.newBufferedReader(Paths.get(pathToClientSecretsFile), UTF_8));
    
    // Set up the authorization code flow.
    //
    // Note: providing a DataStoreFactory allows auth credentials to be cached, so they survive
    // multiple runs of the program. This avoids prompting the user for authorization every time the
    // access token expires, by remembering the refresh token.
    GoogleAuthorizationCodeFlow flow =
        new GoogleAuthorizationCodeFlow.Builder(
                httpTransport, jsonFactory, clientSecrets, OAUTH_SCOPES)
            .setDataStoreFactory(dataStoreFactory)
            .build();
    
    // Authorize and persist credentials to the data store.
    //
    // Note: the "user" value below is used to identify a specific set of credentials in the data
    // store. You may provide different values here to persist credentials for multiple users to
    // the same data store.
    Credential credential =
        new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user");
    
  2. Crie um cliente Dfareporting autorizado.

    // Create a Dfareporting client instance.
    //
    // Note: application name below should be replaced with a value that identifies your
    // application. Suggested format is "MyCompany-ProductName/Version.MinorVersion".
    Dfareporting reporting =
        new Dfareporting.Builder(credential.getTransport(), credential.getJsonFactory(), credential)
            .setApplicationName("dfareporting-java-installed-app-sample")
            .build();
    
  3. Realize uma operação.

    // Retrieve and print all user profiles for the current authorized user.
    UserProfileList profiles = reporting.userProfiles().list().execute();
    for (int i = 0; i < profiles.getItems().size(); i++) {
      System.out.printf("%d) %s%n", i + 1, profiles.getItems().get(i).getUserName());
    }
    

PHP

  1. Carregue o arquivo da chave secreta do cliente e gere credenciais de autorização.

    Na primeira vez que fizer isso, será solicitado que você aceite uma mensagem de autorização no navegador. Antes de aceitar, verifique se você fez login usando uma Conta do Google com acesso ao Campaign Manager. Seu aplicativo será autorizado a acessar dados em nome de qualquer conta que estiver conectada no momento.

    // Create a Google_Client instance.
    //
    // Note: application name should be replaced with a value that identifies
    // your application. Suggested format is "MyCompany-ProductName".
    $client = new Google_Client();
    $client->setAccessType('offline');
    $client->setApplicationName('PHP installed app sample');
    $client->setRedirectUri(self::OAUTH_REDIRECT_URI);
    $client->setScopes(self::$OAUTH_SCOPES);
    
    // Load the client secrets file.
    $client->setAuthConfig($pathToJsonFile);
    
    // Try to load cached credentials from the token store. Using a token store
    // allows auth credentials to be cached, so they survive multiple runs of
    // the application. This avoids prompting the user for authorization every
    // time the access token expires, by remembering the refresh token.
    if (file_exists($tokenStore) && filesize($tokenStore) > 0) {
      $client->setAccessToken(file_get_contents($tokenStore));
    } else {
      // If no cached credentials were found, authorize and persist
      // credentials to the token store.
      print 'Open this URL in your browser and authorize the application.';
      printf("\n\n%s\n\n", $client->createAuthUrl());
      print 'Enter the authorization code: ';
      $code = trim(fgets(STDIN));
      $client->authenticate($code);
    
      file_put_contents($tokenStore, json_encode($client->getAccessToken()));
    }
    
  2. Crie um cliente Dfareporting autorizado.

    // Create a Dfareporting service object.
    $service = new Google_Service_Dfareporting($client);
    
  3. Realize uma operação.

    // Retrieve and print all user profiles for the current authorized user.
    $result = $service->userProfiles->listUserProfiles();
    foreach ($result['items'] as $userProfile) {
      printf(
          "User profile \"%s\" (ID: %d) found for account %d.\n",
          $userProfile->getUserName(),
          $userProfile->getProfileId(),
          $userProfile->getAccountId()
      );
    }
    

Python

  1. Carregue o arquivo da chave secreta do cliente e gere credenciais de autorização.

    Na primeira vez que fizer isso, será solicitado que você aceite uma mensagem de autorização no navegador. Antes de aceitar, verifique se você fez login usando uma Conta do Google com acesso ao Campaign Manager. Seu aplicativo será autorizado a acessar dados em nome de qualquer conta que estiver conectada no momento.

    # Set up a Flow object to be used if we need to authenticate.
    flow = client.flow_from_clientsecrets(
        path_to_client_secrets_file, scope=OAUTH_SCOPES)
    
    # Check whether credentials exist in the credential store. Using a credential
    # store allows auth credentials to be cached, so they survive multiple runs
    # of the application. This avoids prompting the user for authorization every
    # time the access token expires, by remembering the refresh token.
    storage = Storage(CREDENTIAL_STORE_FILE)
    credentials = storage.get()
    
    # If no credentials were found, go through the authorization process and
    # persist credentials to the credential store.
    if credentials is None or credentials.invalid:
      credentials = tools.run_flow(flow, storage,
                                   tools.argparser.parse_known_args()[0])
    
    # Use the credentials to authorize an httplib2.Http instance.
    http = credentials.authorize(httplib2.Http())
    
  2. Crie um cliente Dfareporting autorizado.

    # Construct a service object via the discovery service.
    service = discovery.build('dfareporting', 'v3.2', http=http)
    
  3. Realize uma operação.

    # Construct the request.
    request = service.userProfiles().list()
    
    # Execute request and print response.
    response = request.execute()
    
    for profile in response['items']:
      print('Found user profile with ID %s and user name "%s".' %
            (profile['profileId'], profile['userName']))
    

Ruby

  1. Carregue o arquivo da chave secreta do cliente e gere credenciais de autorização.

    Na primeira vez que fizer isso, será solicitado que você aceite uma mensagem de autorização no navegador. Antes de aceitar, verifique se você fez login usando uma Conta do Google com acesso ao Campaign Manager. Seu aplicativo será autorizado a acessar dados em nome de qualquer conta que estiver conectada no momento.

    # Load client ID from the specified file.
    client_id = Google::Auth::ClientId.from_file(path_to_json_file)
    
    # Set up the user authorizer.
    #
    # Note: providing a token store allows auth credentials to be cached, so they
    # survive multiple runs of the application. This avoids prompting the user for
    # authorization every time the access token expires, by remembering the
    # refresh token.
    authorizer = Google::Auth::UserAuthorizer.new(
        client_id, [API_NAMESPACE::AUTH_DFAREPORTING], token_store)
    
    # Authorize and persist credentials to the data store.
    #
    # Note: the 'user' value below is used to identify a specific set of
    # credentials in the token store. You may provide different values here to
    # persist credentials for multiple users to the same token store.
    authorization = authorizer.get_credentials('user')
    if authorization.nil?
      puts "Open this URL in your browser and authorize the application."
      puts
      puts authorizer.get_authorization_url(base_url: OAUTH_REDIRECT_URI)
      puts
      puts "Enter the authorization code:"
      code = STDIN.gets.chomp
      authorization = authorizer.get_and_store_credentials_from_code(
          base_url: OAUTH_REDIRECT_URI, code: code, user_id: 'user')
    end
    
  2. Crie um cliente Dfareporting autorizado.

    # Create a Dfareporting service object.
    #
    # Note: application name should be replaced with a value that identifies
    # your application. Suggested format is "MyCompany-ProductName".
    service = API_NAMESPACE::DfareportingService.new
    service.authorization = authorization
    service.client_options.application_name = "Ruby installed app sample"
    service.client_options.application_version = '1.0.0'
    
  3. Realize uma operação.

    // Retrieve and print all user profiles for the current authorized user.
    UserProfileList profiles = service.UserProfiles.List().Execute();
    
    foreach (UserProfile profile in profiles.Items) {
      Console.WriteLine("Found user profile with ID {0} and name \"{1}\".",
          profile.ProfileId, profile.UserName);
    }
    

Saiba mais

Acesse a referência da API para saber mais sobre todos os serviços que ela oferece. Todas as páginas de detalhes dos métodos contam com exploradores de API incorporados que você pode usar para fazer solicitações de teste diretamente no navegador.

Consulte nossos outros guias para ver tópicos avançados e exemplos detalhados de tarefas comuns.

Quando você estiver pronto para começar a criar códigos, veja nossa coleção abrangente de amostras de código, que podem ser modificadas e ampliadas de acordo com suas necessidades.