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:

  1. Prepara un Destination per ricevere i dati sul pubblico.
  2. Prepara i dati del segmento di pubblico da inviare.
  3. Crea una richiesta IngestionService per i membri del pubblico.
  4. Invia la richiesta con Explorer API di Google.
  5. 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:

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • Imposta operatingAccount sul tipo di account e sull'ID dell'account che riceverà i dati del pubblico.

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:

  1. Rimuovi tutti gli spazi vuoti iniziali, finali e intermedi.
  2. Converti l'indirizzo email in minuscolo.
  3. Esegui l'hashing dell'indirizzo email utilizzando l'algoritmo SHA-256.
  4. 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

Combina Destination e userData per il corpo della richiesta:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_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
}
  1. Aggiorna i segnaposto nel corpo, ad esempio OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID e AUDIENCE_ID con i valori per il tuo account e la tua destinazione.
  2. Imposta validateOnly su true per convalidare la richiesta senza applicare le modifiche. Quando è tutto pronto per applicare le modifiche, imposta validateOnly su false.
  3. Imposta termsOfService per indicare che l'utente ha accettato i Termini di servizio Customer Match.
  4. Tieni presente che questa richiesta indica che consent è concesso e non utilizza la crittografia.

Invia la richiesta

  1. Copia il corpo della richiesta utilizzando il pulsante di copia in alto a destra nell'esempio.
  2. Fai clic sul pulsante API nella barra degli strumenti.
  3. Incolla il corpo della richiesta copiato nella casella Corpo della richiesta.
  4. Fai clic sul pulsante Esegui, completa le richieste di autorizzazione ed esamina la risposta.

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 email_address contenente una stringa di testo normale anziché un valore con codifica 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 email_address 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. 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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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

Indietro
Panoramica dei segmenti di pubblico