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 del 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": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

  • Imposta operatingAccount sul prodotto e sull'ID dell'account che riceverà i dati del segmento di 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": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "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_PRODUCT, 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 e rivedi la risposta.

Risposte riuscite

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

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

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"
          }
        ]
      }
    ]
  }
}

Passaggi successivi