Guida rapida

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

In questa guida rapida, esegui i seguenti passaggi:

  1. Prepara un Destination per ricevere i dati sul pubblico.
  2. Prepara i dati sul pubblico da inviare.
  3. Crea una richiesta IngestionService.
  4. Invia la richiesta con Explorer API di Google.
  5. Comprendi le risposte di successo e di errore.

Preparare 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 sul pubblico.

Preparare i dati sul pubblico

Considera i seguenti dati di esempio in un file delimitato da virgole. Ogni riga del file corrisponde a un membro del segmento di 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 soddisfare 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 dell'hash utilizzando la codifica esadecimale (esadecimale) o la 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 essere stati sottoposti ad hashing e 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 di 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 nel Sample.
  2. Vai alla pagina audienceMembers.ingest.
  3. Fai clic sul pulsante API a destra e poi sul pulsante Prova nella sezione espansa.
  4. Incolla il corpo della richiesta copiato nella casella Corpo della richiesta.
  5. 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 come 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 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 email_address non sottoposto ad hashing e 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]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Passaggi successivi