Configurare l'accesso API

Ecco come configurare l'accesso all'API Data Manager con un SDK o REST.

Prerequisiti

Prima di poter utilizzare l'API Data, assicurati di disporre di quanto segue:

  1. Un progetto Google Cloud.
  2. Un Account Google con l'autorizzazione serviceusage.services.enable sul tuo progetto Google Cloud o con un ruolo che include questa autorizzazione. Ad esempio, roles/owner e roles/serviceusage.serviceUsageAdmin includono entrambi l'autorizzazione serviceusage.services.enable. Per controllare le tue autorizzazioni, consulta Visualizzare l'accesso attuale.

Abilita l'API

Se non l'hai ancora fatto, abilita l'API Data Manager facendo clic su Abilita l'API Data Manager o segui le istruzioni per eseguire questo passaggio manualmente.

Attiva l'API Data Manager

Se non riesci a trovare l'API Data Manager o l'abilitazione dell'API Data Manager non va a buon fine, verifica che il tuo Account Google soddisfi i prerequisiti.

Configura l'autenticazione

Puoi utilizzare uno qualsiasi dei metodi di autenticazione di Google, oltre alle chiavi API. Ti consigliamo di esaminare la sezione Scegliere il metodo di autenticazione giusto per il tuo caso d'uso per decidere quale approccio è più adatto al tuo caso d'uso.

Due metodi di autenticazione comuni sono gli account utente e i service account:

  • Account utente: rappresentano le persone che interagiscono direttamente con le API e i servizi Google.
  • Service account: rappresentano app, non persone, come utenti. Consentono alle tue app di gestire l'autenticazione e l'autorizzazione. Ad esempio, se un'app deve accedere alle risorse Google Cloud.

La tua integrazione può utilizzare le credenziali predefinite dell'applicazione (ADC) per trovare automaticamente le credenziali dall'ambiente, in modo da non dover modificare il codice client per l'autenticazione.

Scegli Account utente o Simulazione dell'identità del service account per configurare ADC:

Ecco i passaggi per l'autenticazione con le credenziali dell'account utente:

  1. Configura le impostazioni della piattaforma Google Auth per il tuo progetto.

    1. Apri la pagina Brand nella console Google Cloud.

    2. Seleziona il progetto.

    3. Compila il modulo e fai clic su Crea.

  2. Poiché l'ambito dell'API Data Manager è un ambito sensibile, sono necessari i seguenti passaggi:

    1. Vai alle impostazioni di accesso ai dati per il tuo progetto.

    2. Fai clic su Aggiungi o rimuovi ambiti.

    3. Seleziona la casella accanto a API Data Manager nell'elenco degli ambiti e fai clic su Aggiorna.

    4. Fai clic su Salva.

    5. Vai a Pubblico nella console Google Cloud e aggiorna lo Stato di pubblicazione e il Tipo di utente. Scopri di più su queste impostazioni in Gestisci il pubblico dell'app.

  3. Fai clic su Crea client OAuth2 per creare un client OAuth2 nel progetto o segui le istruzioni per creare un client OAuth2 Desktop.

    Crea client OAuth2

    Nell'ultimo passaggio, fai clic su SCARICA CONFIGURAZIONE CLIENT e annota la posizione di download che scegli.

  4. Genera un file ADC locale eseguendo il seguente comando. Questo comando avvia un flusso web in cui ti viene chiesto di accedere all'Account Google che utilizzi con l'API.

    Sostituisci PATH_TO_CLIENT_JSON con il nome del file JSON che hai scaricato.

    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. Verifica che le credenziali siano configurate correttamente utilizzando il seguente comando. In caso di esito positivo, il comando stampa un token di accesso nella console.

    gcloud auth application-default print-access-token

Per saperne di più sull'autenticazione e sulle credenziali per la tua app, consulta Metodi di autenticazione di Google e Come funzionano le credenziali predefinite dell'applicazione.

Configurare l'accesso al conto operativo

Concedi all'indirizzo email associato al tuo account utente l'accesso a Destination.

  • Se utilizzi un account Google Ads o di un partner di dati, segui le istruzioni per aggiungere l'email dell'utente all'account.
  • Se utilizzi un account Display & Video 360, segui le istruzioni per aggiungere l'email dell'utente all'account.

Configura l'SDK per il tuo linguaggio di programmazione

Sulla tua macchina locale, installa l'SDK che preferisci:

REST

  1. Aggiorna i segnaposto nel seguente esempio, ad esempio OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID e AUDIENCE_ID, con i valori per il tuo account e la tua destinazione.
  2. Sostituisci PROJECT_ID con l'ID del tuo Google Cloud.

  3. Copia l'esempio nella riga di comando per inviare la richiesta.

    Rimuovi l'attributo linkedAccount della voce in destinations se non accedi a operatingAccount utilizzando un link prodotto stabilito.

    #!/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": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "accountType": "LINKED_ACCOUNT_TYPE",
        "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

installa la libreria client

Segui le istruzioni riportate nella guida all'installazione della libreria client.NET per aggiungere una dipendenza alla libreria client nel tuo progetto.

(Facoltativo) Ottieni la libreria di utilità e gli esempi di codice.

  1. Scarica ed estrai data-manager-dotnet.tar.gz.

  2. Nel tuo progetto .NET, dichiara una dipendenza ProjectReference dalla libreria di utilità. Sostituisci PATH_TO_UTILITY_LIBRARY con il percorso in cui hai estratto la directory data-manager-dotnet da data-manager-dotnet.tar.gz.

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

  3. Per formattare i dati, utilizza l'utilità Formatter nel tuo progetto .NET.

  4. Sfoglia gli esempi di codice nella sottodirectory samples.

    Passa alla directory samples e utilizza dotnet run per ottenere l'elenco dei campioni disponibili.

    dotnet run

    Passa l'argomento --help quando esegui un esempio per stampare un'istruzione di utilizzo con i parametri previsti.

    dotnet run -- ingest-audience-members --help

    Per iniziare con alcuni dati di esempio, utilizza il file all'indirizzo samples/sampledata/audience_members_1.csv.

Java

installa la libreria client

  1. Scarica ed estrai google-cloud-ads-datamanager-v1-java.tar.gz.
  2. Vai alla directory google-cloud-ads-datamanager-v1-java.

  3. Esegui questo comando per creare e pubblicare la libreria nel tuo repository Maven locale da utilizzare con Maven o Gradle.

    ./gradlew install

  4. Nel tuo progetto Java, dichiara una dipendenza dalla libreria dell'API Data Manager.

    Gradle:

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

    Maven:

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

(Facoltativo) Ottieni la libreria di utilità e gli esempi di codice.

  1. Clona il repository GitHub.

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

  2. Vai alla directory data-manager-java.

  3. Crea e pubblica la libreria di utilità nel repository Maven locale.

    ./gradlew data-manager-util:install

  4. Nel tuo progetto Java, dichiara una dipendenza dalla libreria di utilità.

    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. Per formattare e criptare i dati, utilizza le utilità UserDataFormatter e Encrypter nel tuo progetto Java.

  6. Sfoglia gli esempi di codice nella sottodirectory data-manager-samples o su GitHub. Per eseguire un esempio dalla riga di comando, utilizza l'attività Gradle run.

    Ad esempio, il seguente comando esegue l'esempio IngestAudienceMembers e stampa un'istruzione di utilizzo:

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

    Per iniziare con alcuni dati di esempio, utilizza il file all'indirizzo data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Node.js

installa la libreria client

  1. Scarica ed estrai ads-datamanager-v1-nodejs.tar.gz.
  2. Vai alla directory ads-datamanager-v1-nodejs.

  3. Esegui questo comando per compilare e comprimere la libreria client in un file .tgz da utilizzare con npm.

    npm pack

    Il comando genera un archivio denominato google-cloud-datamanager-0.1.4.tgz. Prendi nota della posizione del file in modo da poterlo utilizzare nei passaggi successivi.

  4. Nel tuo progetto Node.js, dichiara una dipendenza dalla libreria client dell'API Data Manager aggiungendo una voce dependencies per il percorso completo e il nome del file google-cloud-datamanager-0.1.4.tgz.

    {
   "dependencies": {
      ...
      "@google-cloud/datamanager": "file:PATH_TO_CLIENT_LIBRARY/google-cloud-datamanager-0.1.4.tgz",
      ...
   }
}

(Facoltativo) Ottieni la libreria di utilità e gli esempi di codice.

  1. Scarica ed estrai data-manager-node.tar.gz.
  2. Vai alla directory data-manager-node.

  3. Passa alla directory util.

    cd util

  4. Esegui questo comando per compilare e comprimere la libreria di utilità in un file .tgz da utilizzare con npm.

    npm pack

    Il comando genera un archivio denominato google-ads-datamanager-util-0.1.0.tgz. Prendi nota della posizione del file in modo da poterlo utilizzare nei passaggi successivi.

  5. Nel tuo progetto Node.js, dichiara una dipendenza dalla libreria di utilità dell'API Data Manager aggiungendo una voce dependencies per il percorso completo e il nome del file google-ads-datamanager-util-0.1.0.tgz.

    {
   "dependencies": {
      ...
      "@google-ads/data-manager-util": "file:PATH_TO_UTILITY_LIBRARY/google-ads-datamanager-util-0.1.0.tgz",
      ...
   }
}

    Per formattare i dati, utilizza l'utilità UserDataFormatter nel tuo progetto Node.js.

  6. Sfoglia gli esempi di codice nella sottodirectory samples. Esegui gli esempi seguendo questi passaggi:

    1. Copia google-cloud-datamanager-0.1.4.tgz nella directory principale della directory data-manager-node.

    2. Vai alla directory samples nella sezione data-manager-node.

    3. Esegui questo comando per compilare gli esempi.

      npm run compile

    4. Esegui gli esempi, passando gli argomenti richiesti. Passa l'argomento --help quando esegui un esempio per stampare un'istruzione di utilizzo con i parametri previsti.

      Ad esempio, il seguente comando esegue l'esempio ingest_audience_members e stampa un'istruzione di utilizzo:

      npx ts-node audiences/ingest_audience_members.ts --help

    Per iniziare con alcuni dati di esempio, utilizza il file all'indirizzo samples/sampledata/audience_members_1.csv.

PHP

installa la libreria client

  1. Scarica ed estrai google-cloud-ads-datamanager-v1-php.tar.gz.
  2. Vai alla directory google-cloud-ads-datamanager-v1-php.

  3. Esegui questo comando per risolvere le dipendenze della libreria:

    composer update --prefer-dist

  4. Nel file composer.json del tuo progetto PHP sullo stesso host, dichiara una dipendenza dalla libreria dell'API Data Manager seguendo questi passaggi:

    1. Aggiungi una sezione repositories che rimanda alla posizione della directory google-cloud-ads-datamanager-v1-php.

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

    2. Dichiara una dipendenza dalla libreria API Data Manager.

      "require": {
   "googleads/data-manager": "0.1.4"
}

(Facoltativo) Ottieni la libreria di utilità e gli esempi di codice.

  1. Scarica ed estrai data-manager-php.tar.gz.
  2. Vai alla directory data-manager-php.

  3. Esegui questo comando per risolvere le dipendenze della libreria:

    composer update --prefer-dist

  4. Nel file composer.json del tuo progetto PHP sullo stesso host, dichiara una dipendenza dalla libreria di utilità seguendo questi passaggi:

    1. Aggiungi una voce nella sezione repositories che rimandi alla posizione della directory data-manager-php.

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

    2. Dichiara una dipendenza dalla libreria di utilità.

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

    Per formattare i dati, utilizza l'utilità Formatter nel tuo progetto PHP.

  5. Sfoglia gli esempi di codice nella sottodirectory samples. Esegui gli esempi seguendo questi passaggi:

    1. Vai alla directory samples.

    2. Imposta la variabile di ambiente DATA_MANAGER_PHP_LIB sul percorso in cui hai estratto la libreria client.

      export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"

    3. Esegui questo comando per risolvere le dipendenze della libreria:

      composer update --prefer-dist

    4. Esegui gli esempi, passando gli argomenti richiesti. Passa l'argomento --help quando esegui un esempio per stampare un'istruzione di utilizzo con i parametri previsti.

    Per iniziare con alcuni dati di esempio, utilizza il file all'indirizzo samples/sampledata/audience_members_1.csv.

Python

installa la libreria client

  1. Scarica ads-datamanager-v1-py.tar.gz.
  2. Vai alla directory del download.

  3. Esegui questo comando per creare la libreria e renderla disponibile per altri progetti nello stesso ambiente Python:

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

  4. Nel tuo progetto Python, dichiara una dipendenza dalla libreria dell'API Data Manager. Ad esempio, se utilizzi un file requirements.txt nel progetto, aggiungi la seguente riga al file:

    google-ads-data-manager=0.1.4

(Facoltativo) Ottieni la libreria di utilità e gli esempi di codice.

  1. Scarica ed estrai data-manager-python.tar.gz.
  2. Vai alla directory data-manager-python.

  3. Per installare la libreria di utilità nel tuo ambiente Python, esegui questo comando:

    pip install .

  4. Nel tuo progetto Python, dichiara una dipendenza dalla libreria di utilità. Ad esempio, se utilizzi un file requirements.txt nel tuo progetto, aggiungi la seguente riga al file:

    google-ads-data-manager-util=0.1.0

  5. Per formattare e criptare i dati, utilizza le utilità Formatter e Encrypter nel tuo progetto Python.

  6. Sfoglia gli esempi di codice nella sottodirectory samples. Passa l'argomento --help quando esegui un esempio per stampare un'istruzione di utilizzo con i parametri previsti.

    Per iniziare con alcuni dati di esempio, utilizza il file all'indirizzo samples/sampledata/audience_members_1.csv.

Ruby

installa la libreria client

Segui le istruzioni riportate nella guida all'installazione della libreria client Ruby per aggiungere una dipendenza alla libreria client nel tuo progetto.

Passaggi successivi