Guide de démarrage rapide

Vous pouvez suivre ce guide de démarrage rapide pour vous familiariser avec l'API Data Manager. Choisissez la version du guide de 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 des données d'audience.
  2. Préparez les données d'audience à envoyer.
  3. Créez une requête IngestionService.
  4. Envoyez la requête à l'aide de 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 données seront envoyées. 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

Examinez les exemples de données suivants dans un fichier de valeurs séparées par des virgules. Chaque ligne du fichier correspond à un membre de l'audience, et chaque membre possède 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 de hachage à l'aide de l'hexadécimal (hex) ou de l'encodage en base64. Les exemples de ce guide utilisent un encodage hexadécimal.

Voici les données formatées:

#,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 à partir 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. Mettez à jour 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 la méthode consent est accordée et qu'elle n'utilise pas le chiffrement.

Envoyer la requête

  1. Copiez le corps de la requête à l'aide du bouton "Copy" (Copier) 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 Exécuter, suivez les invites d'autorisation et examinez la réponse.

Réponses de réussite

Si vous avez laissé le champ validateOnly défini sur true, une requête réussie génère un code d'état de la réponse 200 OK et un objet vide dans le corps de la réponse.

{
}

Si vous définissez validateOnly sur false, 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

Quel que soit le paramètre validateOnly, 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 les détails de 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"
          }
        ]
      }
    ]
  }
}

Une valeur email_address qui n'est pas hachée et qui n'est encodée qu'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