Inviare membri del segmento di pubblico

Puoi seguire questa guida rapida per acquisire familiarità con l'API Data Manager. Scegli la versione della guida rapida che vuoi visualizzare:

In questa guida rapida, completerai i seguenti passaggi:

Prepara un Destination per ricevere i dati del pubblico.
Prepara i dati del segmento di pubblico da inviare.
Crea una richiesta IngestionService per i membri del pubblico.
Invia la richiesta con Explorer API di Google.
Comprendere le risposte di successo e di errore.

Prepara una destinazione

Prima di poter inviare i dati, devi preparare la destinazione a cui inviarli. Ecco un Destination di esempio che puoi utilizzare. Consulta Configura le destinazioni per esempi di destinazioni per diversi scenari.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

Imposta operatingAccount sul tipo di account e sull'ID dell'account che riceverà i dati del pubblico.
Se le tue credenziali OAuth sono per un utente con accesso a un account amministratore Google Ads che ha operatingAccount come uno dei suoi subaccount, imposta loginAccount sul tipo di account e sull'ID dell'account amministratore.
Se le credenziali OAuth sono per un utente con accesso diretto a operatingAccount, non devi impostare loginAccount.

Preparare i dati sul pubblico

Considera i seguenti dati di esempio in un file separato da virgole. Ogni riga del file corrisponde a un membro del pubblico e ogni membro ha fino a tre indirizzi email.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

Gli indirizzi email devono rispettare i seguenti requisiti di formattazione e hashing:

Rimuovi tutti gli spazi vuoti iniziali, finali e intermedi.
Converti l'indirizzo email in minuscolo.
Esegui l'hashing dell'indirizzo email utilizzando l'algoritmo SHA-256.
Codifica i byte hash utilizzando esadecimale (esadecimale) o codifica Base64. Gli esempi in questa guida utilizzano la codifica esadecimale.

Ecco i dati formattati:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

Ecco i dati dopo l'hashing e la codifica:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

Ecco un esempio di AudienceMember per gli indirizzi email formattati, sottoposti ad hashing e codificati di dana@example.com e danam@example.com della prima riga dei dati di input:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

Crea il corpo della richiesta

Per creare il corpo della richiesta, combina destinations e audienceMembers, imposta il campo encoding e aggiungi gli altri campi della richiesta che vuoi includere, ad esempio validateOnly e consent.

Se invii membri del pubblico per Customer Match, imposta termsOfService per indicare se l'utente ha accettato i Termini di servizio di Customer Match.

Gli esempi in questa guida non utilizzano la crittografia, ma puoi seguire le istruzioni riportate in Criptare i dati utente per aggiungere la crittografia al tuo processo.

Invia la richiesta

Fai clic su Apri in Explorer API per aprire Explorer API in una nuova scheda o finestra.
Nel corpo della richiesta in Explorer API, sostituisci ogni stringa che inizia con REPLACE_WITH, ad esempio REPLACE_WITH_OPERATING_ACCOUNT_TYPE, con il valore pertinente.
Fai clic su Esegui nella parte inferiore della pagina di API Explorer e completa le richieste di autorizzazione per inviare la richiesta.
Imposta validateOnly su true per convalidare la richiesta senza applicare le modifiche. Quando è tutto pronto per applicare le modifiche, imposta validateOnly su false.

Richiesta di importazione

Apri in Explorer API

{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_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
}

Risposte riuscite

Una richiesta riuscita restituisce una risposta con un oggetto contenente un requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Registra il requestId restituito in modo da poter recuperare la diagnostica man mano che ogni destinazione nella richiesta viene elaborata.

Risposte di errore

Una richiesta non riuscita genera un codice di stato di risposta di errore, ad esempio 400 Bad Request, e una risposta con i dettagli dell'errore.

Ad esempio, un emailAddress contenente una stringa di testo normale anziché un valore codificato in esadecimale produce la seguente risposta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Un emailAddress non sottoposto ad hashing e codificato solo in formato esadecimale produce la seguente risposta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Inviare eventi per più destinazioni

Se i tuoi dati contengono membri del segmento di pubblico per destinazioni diverse, puoi inviarli nella stessa richiesta utilizzando i riferimenti alle destinazioni.

Ad esempio, se hai un membro del segmento di pubblico per l'ID elenco utenti 11112222 e un altro membro del segmento di pubblico per l'ID elenco utenti 77778888, invia entrambi i membri del segmento di pubblico in un'unica richiesta impostando reference di ogni Destination. Il reference è definito dall'utente. L'unico requisito è che ogni Destination abbia un reference univoco. Ecco l'elenco destinations modificato per la richiesta:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

Imposta il destination_references di ogni AudienceMember per inviarlo a una o più destinazioni specifiche. Ad esempio, ecco un AudienceMember che riguarda solo il primo Destination, quindi il suo elenco destination_references contiene solo il reference del primo Destination:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

Il campo destination_references è un elenco, quindi puoi specificare più destinazioni per un membro del segmento di pubblico. Se non imposti il destination_references di un AudienceMember, l'API Data Manager invia il membro del pubblico a tutte le destinazioni nella richiesta.

Passaggi successivi

Configura l'autenticazione e configura il tuo ambiente con una libreria client.
Scopri di più sui requisiti di formattazione, hashing e codifica per ogni tipo di dati.
Scopri come criptare i dati utente.
Scopri come recuperare i dati di diagnostica per le tue richieste.
Scopri di più sulle best practice.
Scopri di più su limiti e quote.

Indietro

Panoramica dei segmenti di pubblico