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 démarrage rapide que vous souhaitez consulter :

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éparez 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 vers laquelle les envoyer. Voici un exemple de Destination que vous pouvez utiliser :

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • Définissez operatingAccount sur le type de compte 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 des virgules. 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 suivantes en termes de format et de hachage :

  1. Supprime 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 de hachage à l'aide de l'encodage hexadécimal (hex) ou 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 hachage et encodage :

#,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 les Destination et userData pour le corps de la requête :

{
  "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. Remplacez les espaces réservés dans le corps, tels que OPERATING_ACCOUNT_TYPE, 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 du ciblage par liste de clients.
  4. Notez que cette requête indique que consent est accordé et n'utilise pas le 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. Cliquez sur le bouton API dans la barre d'outils.
  3. Collez le corps de la requête copié dans la zone Corps de la requête.
  4. Cliquez sur le bouton 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"
}

Enregistrez le requestId renvoyé pour pouvoir récupérer les diagnostics à mesure que chaque destination de la demande est traitée.

Réponses d'échec

Une requête ayant échoué génère un code d'état de réponse d'erreur tel que 400 Bad Request, ainsi qu'une réponse contenant des informations 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 produit 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 non haché et uniquement encodé en hexadécimal produit 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"
          }
        ]
      }
    ]
  }
}

Envoyer des événements pour plusieurs destinations

Si vos données contiennent des membres d'audience pour différentes destinations, vous pouvez les envoyer dans la même requête à l'aide de références de destination.

Par exemple, si vous avez un membre d'audience pour la liste d'utilisateurs dont l'ID est 11112222 et un autre membre d'audience pour la liste d'utilisateurs dont l'ID est 77778888, envoyez les deux membres d'audience dans une seule requête en définissant le reference de chaque Destination. Le reference est défini par l'utilisateur. La seule exigence est que chaque Destination possède un reference unique. Voici la liste destinations modifiée pour la demande :

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

Définissez le destination_references de chaque AudienceMember pour l'envoyer à une ou plusieurs destinations spécifiques. Par exemple, voici un AudienceMember qui ne concerne que le premier Destination. Sa liste destination_references ne contient donc que le reference du premier Destination :

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

Le champ destination_references est une liste. Vous pouvez donc spécifier plusieurs destinations pour un membre de l'audience. Si vous ne définissez pas le destination_references d'un AudienceMember, l'API Data Manager envoie le membre de l'audience à toutes les destinations de la demande.

Étapes suivantes

Précédent
Présentation des audiences