Envoyer des membres de l'audience

Vous pouvez suivre ce guide de démarrage rapide pour vous familiariser avec l'API Data Manager. Choisissez la version du tutoriel de démarrage que vous souhaitez afficher:

Dans ce guide de démarrage rapide, vous allez effectuer les étapes suivantes :

  1. Préparez un Destination pour recevoir les données d'audience.
  2. Préparer les données d'audience à envoyer
  3. Créez une requête IngestionService pour les membres de l'audience.
  4. Envoyez la requête avec Google APIs Explorer.
  5. Comprendre les réponses de réussite et d'échec

Préparer une destination

Avant de pouvoir envoyer des données, vous devez préparer la destination à laquelle les envoyer. Voici un exemple de Destination à utiliser :

    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

  • Définissez operatingAccount sur le produit et l'ID du compte qui recevra les données d'audience.

Préparer les données d'audience

Prenons l'exemple de données suivant dans un fichier séparé par une virgule. Chaque ligne du fichier correspond à un membre de l'audience, et chaque membre peut avoir jusqu'à trois adresses e-mail.

#,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,

Les adresses e-mail doivent respecter les exigences de mise en forme et de hachage suivantes:

  1. Supprimez tous les espaces blancs de début, de fin et intermédiaires.
  2. Convertissez l'adresse e-mail en minuscules.
  3. Hachez l'adresse e-mail à l'aide de l'algorithme SHA-256.
  4. Encodez les octets du hachage à l'aide de l'encodage hexadécimal (hexadécimal) ou de l'encodage Base64. Les exemples de ce guide utilisent l'encodage hexadécimal.

Voici les données mises en forme:

#,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,

Voici les données après avoir été hachées et encodées:

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

Voici un exemple de AudienceMember pour les adresses e-mail formatées, hachées et encodées de dana@example.com et danam@example.com de la première ligne des données d'entrée :

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

Créer le corps de la requête

Combinez Destination et userData pour le corps de la requête :

{
  "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. Remplacez les espaces réservés dans le corps, tels que OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID et AUDIENCE_ID, par les valeurs de votre compte et de votre destination.
  2. Définissez validateOnly sur true pour valider la requête sans appliquer les modifications. Lorsque vous êtes prêt à appliquer les modifications, définissez validateOnly sur false.
  3. Définissez termsOfService pour indiquer que l'utilisateur a accepté les conditions d'utilisation de Customer Match.
  4. Notez que cette requête indique que consent est accordé et qu'elle n'utilise pas de chiffrement.

Envoyer la requête

  1. Copiez le corps de la requête à l'aide du bouton de copie en haut à droite de l'exemple.
  2. Accédez à la page audienceMembers.ingest.
  3. Cliquez sur le bouton API à droite, puis sur le bouton Essayer dans la section développée.
  4. Collez le corps de la requête copié dans la zone Request body (Corps de la requête).
  5. Cliquez sur le bouton Execute (Exécuter), répondez aux invites d'autorisation et examinez la réponse.

Réponses de réussite

Une requête réussie renvoie une réponse avec un objet contenant un requestId.

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

Réponses en cas d'échec

Une requête ayant échoué génère un code d'état de réponse d'erreur, tel que 400 Bad Request, et une réponse contenant des détails sur l'erreur.

Par exemple, un email_address contenant une chaîne de texte brut au lieu d'une valeur encodée en hexadécimal génère la réponse suivante :

{
  "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 qui n'est pas haché et qui n'est encodé qu'en hexadécimal génère la réponse suivante:

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

Étapes suivantes