Configura el acceso a la API

A continuación, se explica cómo configurar el acceso a la API de Data Manager con un SDK o REST.

Requisitos previos

Antes de usar la API de Data, asegúrate de tener lo siguiente:

  1. Un proyecto de Google Cloud
  2. Una Cuenta de Google que cumpla con los siguientes criterios:
    1. Se te otorgó acceso a la API de Data Manager después de que completaste el formulario de interés en la API de Data Manager. Si puedes ver la página de detalles del producto de API, tienes acceso.
    2. Tiene el permiso serviceusage.services.enable en tu proyecto de Google Cloud o tiene un rol que incluye ese permiso. Por ejemplo, roles/owner y roles/serviceusage.serviceUsageAdmin incluyen el permiso serviceusage.services.enable. Para verificar tus permisos, consulta Cómo ver el acceso actual.

Habilita la API

Si aún no lo hiciste, haz clic en Habilita la API de Data Manager o sigue las instrucciones para realizar este paso de forma manual.

Habilita la API de Data Manager

Si no encuentras la API de Data Manager o si falla la opción Habilitar la API de Data Manager, verifica que tu Cuenta de Google cumpla con los requisitos previos.

Configura la autenticación

Puedes usar cualquiera de los métodos de autenticación de Google, además de las claves de API. Te recomendamos que revises cómo elegir el método de autenticación correcto para tu caso de uso y decidas qué enfoque es adecuado para tu caso de uso.

Dos métodos de autenticación comunes son las cuentas de usuario y las cuentas de servicio:

  • Cuentas de usuario: Representan a las personas que interactúan directamente con los servicios y las APIs de Google.
  • Cuentas de servicio: Representan a las apps, no a las personas, como usuarios. Permiten que tus apps administren la autenticación y la autorización. Por ejemplo, si una app necesita acceder a recursos de Google Cloud.

Tu integración puede usar las credenciales predeterminadas de la aplicación (ADC) para encontrar automáticamente las credenciales del entorno, de modo que no tengas que cambiar el código del cliente para autenticarte.

Elige Cuenta de usuario o Suplantación de identidad de cuenta de servicio para configurar ADC:

Estos son los pasos para autenticarte con credenciales de cuenta de usuario:

  1. Configura los parámetros de Google Auth Platform para tu proyecto.

    1. Abre la página de la marca en la consola de Google Cloud.

    2. Elige tu proyecto.

    3. Completa el formulario y haz clic en Crear.

  2. Dado que el alcance de la API de Data Manager es un alcance sensible, se requieren los siguientes pasos:

    1. Ve a la configuración de Acceso a los datos de tu proyecto.

    2. Haz clic en Agregar o quitar permisos.

    3. Marca la casilla junto a Data Manager API en la lista de permisos y haz clic en Actualizar.

    4. Haz clic en Guardar.

    5. Ve a Público en la consola de Google Cloud y actualiza el Estado de publicación y el Tipo de usuario. Obtén más información sobre estos parámetros de configuración en Administrar público de la aplicación.

  3. Haz clic en Crear cliente de OAuth2 para crear un cliente de OAuth2 en el proyecto o sigue las instrucciones para crear un cliente de OAuth2 de escritorio.

    Crea un cliente de OAuth2

    En el último paso, haz clic en DESCARGAR CONFIGURACIÓN DEL CLIENTE y anota la ubicación de descarga que elijas.

  4. Ejecuta el siguiente comando para generar un archivo ADC local. Este comando inicia un flujo web en el que se te solicita que accedas a la Cuenta de Google que usas con la API.

    Reemplaza PATH_TO_CLIENT_JSON por el nombre del archivo JSON que descargaste.

    gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file="PATH_TO_CLIENT_JSON"

  5. Confirma que las credenciales estén configuradas correctamente con el siguiente comando. Si se ejecuta correctamente, el comando imprimirá un token de acceso en la consola.

    gcloud auth application-default print-access-token

Para obtener más información sobre la autenticación y las credenciales de tu app, consulta Métodos de autenticación en Google y Cómo funcionan las credenciales predeterminadas de la aplicación.

Configura el acceso a la cuenta operativa

Otorga a la dirección de correo electrónico asociada a tu cuenta de usuario acceso a Destination.

  • Si usas una cuenta de Google Ads o de socio de datos, sigue las instrucciones para agregar el correo electrónico del usuario a la cuenta.
  • Si usas una cuenta de Display & Video 360, sigue las instrucciones para agregar la dirección de correo electrónico del usuario a la cuenta.

Configura el SDK para tu lenguaje de programación

En tu máquina local, instala el SDK que prefieras:

REST

  1. Actualiza los marcadores de posición en la siguiente muestra, como OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID y AUDIENCE_ID, con los valores de tu cuenta y destino.
  2. Reemplaza PROJECT_ID por el ID de tu proyecto de Google Cloud.

  3. Copia la muestra en la línea de comandos para enviar la solicitud.

    Quita el atributo linkedAccount de la entrada en destinations si no accedes a operatingAccount a través de un vínculo de producto establecido.

    #!/bin/bash

# Uses gcloud to get an access token. If the Application Default
# Credentials aren't for a service account, the command that specifies
# --scopes fails. This sample falls back to the command without the
# --scopes argument.
DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
  gcloud auth application-default print-access-token)"

# Fetches and prints the scope information for the access token. If you
# get scope-related errors when you send the request in the next step,
# verify that this output includes the Data Manager API scope:
#   https://www.googleapis.com/auth/datamanager
curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"

# Sends the request.
curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
  --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
  --header "x-goog-user-project: PROJECT_ID" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "destinations": [
    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "product": "LOGIN_ACCOUNT_PRODUCT",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "product": "LINKED_ACCOUNT_PRODUCT",
        "accountId": "LINKED_ACCOUNT_ID"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
EOF

.NET

  1. Descarga y extrae google-cloud-ads-datamanager-v1-csharp.tar.gz.

  2. En tu proyecto de .NET, declara una dependencia ProjectReference en la biblioteca de la API de Data Manager. Reemplaza PATH_TO_CLIENT_LIBRARY por la ubicación en la que extrajiste el directorio google-cloud-ads-datamanager-v1-csharp de google-cloud-ads-datamanager-v1-csharp.tar.gz.

    <ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />

  3. Opcional. Obtén la biblioteca de utilidades y las muestras de código.

    1. Descarga y extrae data-manager-dotnet.tar.gz.

    2. En tu proyecto de .NET, declara una dependencia ProjectReference en la biblioteca de utilidades. Reemplaza PATH_TO_UTILITY_LIBRARY por la ubicación en la que extrajiste el directorio data-manager-dotnet de data-manager-dotnet.tar.gz.

      <ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

    3. Para dar formato a los datos, usa la utilidad Formatter en tu proyecto de .NET.

    4. Explora las muestras de código en el subdirectorio samples.

      Para ejecutar las muestras de código, configura la variable de entorno DATA_MANAGER_DOTNET_LIB en la ubicación en la que extrajiste el directorio google-cloud-ads-datamanager-v1-csharp de google-cloud-ads-datamanager-v1-csharp.tar.gz.

      export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"

      Cambia al directorio samples y usa dotnet run para obtener la lista de muestras disponibles.

      dotnet run --framework net8.0

      Pasa el argumento --help cuando ejecutes una muestra para imprimir una declaración de uso con los parámetros esperados.

      dotnet run --framework net8.0 -- ingest-audience-members --help

      Para ayudarte a comenzar con algunos datos de muestra, usa el archivo en samples/sampledata/audience_members_1.csv.

Java

  1. Descarga y extrae google-cloud-ads-datamanager-v1-java.tar.gz.
  2. Navega al directorio google-cloud-ads-datamanager-v1-java.

  3. Ejecuta el siguiente comando para compilar y publicar la biblioteca en tu repositorio local de Maven para usarla con Maven o Gradle.

    ./gradlew -Pversion=0.1.0 install

  4. En tu proyecto de Java, declara una dependencia en la biblioteca de la API de Data Manager.

    Gradle:

    implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.0'

    Maven:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
  <version>0.1.0</version>
</dependency>

  5. Opcional. Obtén la biblioteca de utilidades y las muestras de código.

    1. Clona el repositorio de GitHub.

      git clone https://github.com/googleads/data-manager-java.git

    2. Navega al directorio data-manager-java.

    3. Compila y publica la biblioteca de utilidades en tu repositorio local de Maven.

      ./gradlew data-manager-util:install

    4. En tu proyecto de Java, declara una dependencia en la biblioteca de utilidades.

      Gradle:

      implementation 'com.google.api-ads:data-manager-util:0.1.0'

      Maven:

      <dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.1.0</version>
</dependency>

    5. Para formatear y encriptar los datos, usa las utilidades UserDataFormatter y Encrypter en tu proyecto de Java.

    6. Explora las muestras de código en el subdirectorio data-manager-samples o en GitHub. Para ejecutar una muestra desde la línea de comandos, usa la tarea run de Gradle.

      Por ejemplo, el siguiente comando ejecuta la muestra IngestAudienceMembers y muestra una declaración de uso:

      ./gradlew data-manager-samples:run \
  --args='IngestAudienceMembers --help'

      Para ayudarte a comenzar con algunos datos de muestra, usa el archivo en data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Python

  1. Descarga ads-datamanager-v1-py.tar.gz.
  2. Navega al directorio de la descarga.

  3. Ejecuta el siguiente comando para compilar la biblioteca y hacerla disponible para otros proyectos en el mismo entorno de Python:

    pip install ./ads-datamanager-v1-py.tar.gz

  4. En tu proyecto de Python, declara una dependencia en la biblioteca de la API de Data Manager. Por ejemplo, si usas un archivo requirements.txt en tu proyecto, agrega la siguiente línea al archivo:

    google-ads-data-manager=0.1.0

  5. Opcional. Obtén la biblioteca de utilidades y las muestras de código.

    1. Descarga y extrae data-manager-python.tar.gz.
    2. Navega al directorio data-manager-python.

    3. Para instalar la biblioteca de utilidades en tu entorno de Python, ejecuta el siguiente comando:

      pip install .

    4. En tu proyecto de Python, declara una dependencia en la biblioteca de utilidades. Por ejemplo, si usas un archivo requirements.txt en tu proyecto, agrega la siguiente línea al archivo:

      google-ads-data-manager-util=0.1.0

    5. Para formatear y encriptar los datos, usa las utilidades Formatter y Encrypter en tu proyecto de Python.

    6. Explora las muestras de código en el subdirectorio samples. Pasa el argumento --help cuando ejecutes una muestra para imprimir una declaración de uso con los parámetros esperados.

      Para ayudarte a comenzar con algunos datos de muestra, usa el archivo en samples/sampledata/audience_members_1.csv.

Node.js

  1. Descarga y extrae ads-datamanager-v1-nodejs.tar.gz.
  2. Navega al directorio ads-datamanager-v1-nodejs.

  3. Ejecuta los siguientes comandos para compilar y empaquetar la biblioteca en un archivo .tgz para usarlo con npm.

    npm install
npm pack

    Los comandos generan un archivo llamado google-cloud-datamanager-0.1.0.tgz.

  4. En tu proyecto de Node.js, declara una dependencia en la biblioteca de la API de Data Manager agregando una entrada dependencies para la ruta de acceso completa y el nombre de archivo del archivo google-cloud-datamanager-0.1.0.tgz.

PHP

  1. Descarga y extrae google-cloud-ads-datamanager-v1-php.tar.gz.
  2. Navega al directorio google-cloud-ads-datamanager-v1-php.

  3. Ejecuta el siguiente comando para resolver las dependencias de la biblioteca:

    composer update --prefer-dist

  4. En el archivo composer.json de tu proyecto de PHP en el mismo host, declara una dependencia en la biblioteca de la API de Data Manager con los siguientes pasos:

    1. Agrega una sección repositories que apunte a la ubicación del directorio google-cloud-ads-datamanager-v1-php.

      "repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_CLIENT_LIBRARY"
   }
]

    2. Declara una dependencia en la biblioteca de la API de Data Manager.

      "require": {
   "googleads/data-manager": "^0.1.0"
}

  5. (Opcional) Obtén la biblioteca de utilidades y las muestras de código.

    1. Descarga y extrae data-manager-php.tar.gz.
    2. Navega al directorio data-manager-php.

    3. Ejecuta el siguiente comando para resolver las dependencias de la biblioteca:

      composer update --prefer-dist

    4. En el archivo composer.json de tu proyecto de PHP en el mismo host, declara una dependencia en la biblioteca de utilidades con los siguientes pasos:

      1. Agrega una entrada en la sección repositories que apunte a la ubicación del directorio data-manager-php.

        "repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_UTILITY_LIBRARY"
   }
]

      2. Declara una dependencia en la biblioteca de utilidades.

        "require": {
   "googleads/data-manager-util": "@dev"
}

      Para formatear datos, usa la utilidad Formatter en tu proyecto de PHP.

    5. Explora las muestras de código en el subdirectorio samples. Ejecuta las muestras con los siguientes pasos:

      1. Navega al directorio samples.

      2. Establece la variable de entorno DATA_MANAGER_PHP_LIB en la ruta de acceso en la que extrajiste la biblioteca cliente.

        export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"

      3. Ejecuta el siguiente comando para resolver las dependencias de la biblioteca:

        composer update --prefer-dist

      4. Ejecuta las muestras y pasa los argumentos necesarios. Pasa el argumento --help cuando ejecutes una muestra para imprimir una declaración de uso con los parámetros esperados.

      Para ayudarte a comenzar con algunos datos de muestra, usa el archivo en samples/sampledata/audience_members_1.csv.

Próximos pasos