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 :

Préparez un Destination pour recevoir les données d'audience.
Préparez les données d'audience à envoyer.
Créez une requête IngestionService pour les membres de l'audience.
Envoyez la requête avec Google APIs Explorer.
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. Consultez Configurer des destinations pour obtenir des exemples de destinations pour différents scénarios.

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

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_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.
Si vos identifiants OAuth concernent un utilisateur ayant accès à un compte administrateur Google Ads dont operatingAccount est l'un des sous-comptes, définissez loginAccount sur le type de compte et l'ID du compte administrateur.
Si les identifiants OAuth concernent un utilisateur ayant un accès direct à operatingAccount, vous n'avez pas besoin de définir loginAccount.

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 :

Supprime tous les espaces blancs de début, de fin et intermédiaires.
Convertissez l'adresse e-mail en minuscules.
Hachez l'adresse e-mail à l'aide de l'algorithme SHA-256.
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

Pour créer le corps de la requête, combinez destinations et audienceMembers, définissez le champ encoding, puis ajoutez les autres champs de requête que vous souhaitez inclure, tels que validateOnly et consent.

Si vous envoyez des membres d'audience pour le ciblage par liste de clients, définissez termsOfService pour indiquer si l'utilisateur a accepté les Conditions d'utilisation du ciblage par liste de clients.

Les exemples de ce guide n'utilisent pas le chiffrement, mais vous pouvez suivre les instructions de la section Chiffrer les données utilisateur pour ajouter le chiffrement à votre processus.

Envoyer la requête

Cliquez sur Ouvrir dans l'explorateur d'API pour ouvrir l'explorateur d'API dans un nouvel onglet ou une nouvelle fenêtre.
Dans le corps de la requête de l'API Explorer, remplacez chaque chaîne commençant par REPLACE_WITH, comme REPLACE_WITH_OPERATING_ACCOUNT_TYPE, par la valeur appropriée.
Cliquez sur Exécuter en bas de la page de l'explorateur d'API, puis suivez les invites d'autorisation pour envoyer la requête.
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.

Demande d'ingestion

Ouvrir dans APIs Explorer

{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_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
}

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 emailAddress 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 emailAddress 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": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_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 requête.

Étapes suivantes

Configurez l'authentification et votre environnement à l'aide d'une bibliothèque cliente.
Découvrez les exigences de mise en forme, de hachage et d'encodage pour chaque type de données.
Découvrez comment chiffrer les données utilisateur.
Découvrez comment récupérer les diagnostics pour vos demandes.
Découvrez les bonnes pratiques.
En savoir plus sur les limites et les quotas

Présentation des audiences