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": {
        "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 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. 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 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": {
        "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 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"
}

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

Étapes suivantes