The Data Manager API is in closed beta. To express interest in joining the closed beta, fill out this form.

Questa pagina è stata tradotta dall'API Cloud Translation.

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:

Un progetto Google Cloud.
Un Account Google che soddisfi entrambi i seguenti criteri:
1. Ha ottenuto l'accesso all'API Data Manager dopo aver compilato il modulo di interesse per l'API Data Manager. Se riesci a visualizzare la pagina dei dettagli del prodotto API, hai accesso.
2. Dispone dell'autorizzazione serviceusage.services.enable nel tuo progetto Google Cloud o di 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.

Se non riesci a trovare l'API Data Manager o l'attivazione 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 Rappresentazione service account per configurare ADC:

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

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

Importante :qualsiasi app Google Cloud utilizzata per ottenere le credenziali utente per l'ambito dell'API Data Manager deve essere sottoposta alla verifica OAuth di Google per evitare una schermata dell'interfaccia utente non verificata per i suoi utenti. La verifica OAuth di Google non è richiesta per i service account.
1. Apri la pagina Brand nella console Google Cloud.
2. Seleziona il progetto.
3. Compila il modulo e fai clic su Crea.
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.
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.
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"
```
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

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.
Sostituisci PROJECT_ID con l'ID del tuo Google Cloud.

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": {
        "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

Scarica ed estrai google-cloud-ads-datamanager-v1-csharp.tar.gz.
Nel tuo progetto .NET, dichiara una dipendenza ProjectReference dalla libreria dell'API Data Manager. Sostituisci PATH_TO_CLIENT_LIBRARY con il percorso in cui hai estratto la directory google-cloud-ads-datamanager-v1-csharp da google-cloud-ads-datamanager-v1-csharp.tar.gz.
```
<ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />
```
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.
  
  Per eseguire gli esempi di codice, imposta la variabile di ambiente DATA_MANAGER_DOTNET_LIB sul percorso in cui hai estratto la directory google-cloud-ads-datamanager-v1-csharp da google-cloud-ads-datamanager-v1-csharp.tar.gz.
```
export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"
```
  Passa alla directory samples e utilizza dotnet run per ottenere l'elenco dei campioni disponibili.
```
dotnet run --framework net8.0
```
  Passa l'argomento --help quando esegui un esempio per stampare un'istruzione di utilizzo con i parametri previsti.
```
dotnet run --framework net8.0 -- ingest-audience-members --help
```
  Per iniziare con alcuni dati di esempio, utilizza il file all'indirizzo samples/sampledata/audience_members_1.csv.

Java

Scarica ed estrai google-cloud-ads-datamanager-v1-java.tar.gz.
Vai alla directory google-cloud-ads-datamanager-v1-java.
Esegui questo comando per creare e pubblicare la libreria nel tuo repository Maven locale da utilizzare con Maven o Gradle.
```
./gradlew -Pversion=0.1.0 install
```

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.0'

Maven:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
  <version>0.1.0</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.

Python

Scarica ads-datamanager-v1-py.tar.gz.
Vai alla directory del download.
Esegui il comando seguente per creare la libreria e renderla disponibile ad altri progetti nello stesso ambiente Python:
```
pip install ./ads-datamanager-v1-py.tar.gz
```
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.0
```
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.

Node.js

Scarica ed estrai ads-datamanager-v1-nodejs.tar.gz.
Vai alla directory ads-datamanager-v1-nodejs.
Esegui i seguenti comandi per compilare e comprimere la libreria in un file .tgz da utilizzare con npm.
```
npm install
npm pack
```
I comandi generano un archivio denominato google-cloud-datamanager-0.1.0.tgz.
Nel tuo progetto Node.js, dichiara una dipendenza dalla libreria dell'API Data Manager aggiungendo una voce dependencies per il percorso completo e il nome del file google-cloud-datamanager-0.1.0.tgz.

PHP

Scarica ed estrai google-cloud-ads-datamanager-v1-php.tar.gz.
Vai alla directory google-cloud-ads-datamanager-v1-php.
Esegui questo comando per risolvere le dipendenze della libreria:
```
composer update --prefer-dist
```
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.0"
}
```
(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.

Passaggi successivi

Scopri di più sull'invio dei dati sul pubblico.
Scopri di più sull'invio di eventi.
Sfoglia la documentazione di riferimento REST o RPC.