Mappages de champs

Utilisez les mappages dans les tableaux pour mapper les méthodes et les champs de l'API Google Ads à leur équivalent IngestEventsRequest dans l'API Data Manager.

Méthodes d'API

L'API Data Manager vous permet d'importer chaque lot d'événements de ventes en magasin dans un seul IngestEventsRequest.

En revanche, l'API Google Ads nécessitait un processus en trois étapes à l'aide de OfflineUserDataJobService :

  1. Créer un job à l'aide de CreateOfflineUserDataJob
  2. Ajoutez des opérations au job à l'aide de AddOfflineUserDataJobOperations.
  3. Exécuter le job à l'aide de RunOfflineUserDataJob

Champs des demandes

Chaque IngestEventsRequest est soumis à des limites de requêtes. Si le nombre d'opérations dans votre requête AddOfflineUserDataJobOperations dépasse ces limites, vous devez le répartir sur plusieurs requêtes d'ingestion de l'API Data Manager.

Voici comment les champs des requêtes de l'API Google Ads sont mappés à l'API Data Manager.

CreateOfflineUserDataJobRequest

Le tableau suivant montre comment les champs d'un CreateOfflineUserDataJobRequest sont mappés à un IngestEventsRequest.

CreateOfflineUserDataJobRequest (API Google Ads) IngestEventsRequest (API Data Manager) Remarques
customer_id destinations.operating_account Consultez Champs "Client" et "Action de conversion".
  • developer-token en-tête de requête
  • login-customer_id en-tête de requête
  • linked-customer-id en-tête de requête
 destinations Consultez Champs "Client" et "Action de conversion".
  • job.status
  • job.failure_reason
 Diagnostic Utilisez le request_id renvoyé dans IngestEventsResponse pour récupérer les diagnostics concernant l'importation de vos conversions.
job.id request_id Utilisez le request_id renvoyé dans IngestEventsResponse pour récupérer les diagnostics concernant l'importation de vos conversions.
job.external_id Aucun équivalent
job.type Aucun équivalent
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account Un partenaire pour les données qui importe des conversions de ventes en magasin sera identifié par le login_account d'une destination. Pour en savoir plus, consultez Configurer des destinations.
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time Aucun équivalent
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction Aucun équivalent
job.store_sales_metadata.third_party_metadata.partner_match_fraction Aucun équivalent
job.store_sales_metadata.third_party_metadata.partner_upload_fraction Aucun équivalent
job.store_sales_metadata.third_party_metadata.bridge_map_version_id Aucun équivalent
job.store_sales_metadata.loyalty_fraction Aucun équivalent
job.store_sales_metadata.transaction_upload_fraction Aucun équivalent
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 Mappez-le au champ variable d'un CustomVariable au niveau de l'événement ou d'un ItemCustomVariable au niveau de l'article.
enable_match_rate_range_preview Aucun équivalent
validate_only validate_only
Aucun équivalent consent L'API Google Ads n'accepte que la spécification de consent au niveau de l'événement dans UserData. Pour l'API Data Manager, vous pouvez spécifier le consentement pour tous les événements d'une requête en définissant le champ consent sur IngestEventsRequest. Vous pouvez remplacer cette valeur pour un événement individuel en définissant le champ consent de Event.
Aucun équivalent encoding Obligatoire pour les importations UserData. Définissez-le sur le Encoding utilisé pour les valeurs UserIdentifier.
Aucun équivalent encryption_info Indique si la requête contient des identifiants utilisateur UserData chiffrés. Pour en savoir plus, consultez Chiffrement.

AddOfflineUserDataJobOperationsRequest

Le tableau suivant montre comment les champs d'un AddOfflineUserDataJobOperationsRequest sont mappés à un IngestEventsRequest.

AddOfflineUserDataJobOperationsRequest (API Google Ads) IngestEventsRequest (API Data Manager) Remarques
  • developer-token en-tête de requête
  • login-customer_id en-tête de requête
  • linked-customer-id en-tête de requête
 destinations Consultez Champs "Client" et "Action de conversion".
resource_name Aucun équivalent L'API Data Manager ne nécessite pas de mettre à jour une ressource de job.
enable_partial_failure Aucun équivalent Si IngestEventsRequest réussit, les échecs qui se produisent lors du traitement en aval sont gérés au niveau de l'événement, ce qui peut entraîner un succès partiel. Utilisez Diagnostics pour récupérer l'état de votre import ainsi que les erreurs et les avertissements pour les événements individuels. Si IngestEventsRequest échoue (par exemple, en raison d'un BadRequest), aucun événement n'est traité. Vous devrez résoudre l'erreur et réessayer d'envoyer la requête. Pour en savoir plus, consultez Comprendre les erreurs d'API.
enable_warnings Aucun équivalent Utilisez Diagnostics pour récupérer les avertissements concernant votre requête d'API Data Manager. Vous n'avez pas besoin d'activer cette fonctionnalité.
operations events L'opération OfflineUserDataJobOperation.create équivaut à l'envoi d'un IngestEventsRequest. L'API Data Manager ne prend pas en charge la suppression d'événements.
validate_only validate_only
Aucun équivalent consent L'API Google Ads n'accepte que la spécification de consent au niveau de l'événement dans UserData. Pour l'API Data Manager, vous pouvez spécifier le consentement pour tous les événements d'une requête en définissant le champ consent sur IngestEventsRequest. Vous pouvez remplacer cette valeur pour un événement individuel en définissant le champ consent de Event.
Aucun équivalent encoding Obligatoire pour les importations UserData. Définissez-le sur le Encoding utilisé pour les valeurs UserIdentifier.
Aucun équivalent encryption_info Indique si la requête contient des identifiants utilisateur UserData chiffrés. Pour en savoir plus, consultez Chiffrement.

Champs "Client" et "Action de conversion"

L'API Google Ads nécessite l'en-tête de requête developer-token. Vous devez définir les en-têtes de requête login-customer-id et linked-customer-id pour différents scénarios d'authentification.

L'API Data Manager ne nécessite pas de jeton de développeur. Vous spécifiez les informations de connexion et les informations client associées à l'aide des champs d'un Destination au lieu des en-têtes de requête. Pour en savoir plus sur les destinations, consultez Configurer des destinations.

API Google Ads Destination (API Data Manager) Remarques
customer_id de la demande operating_account Définissez account_id sur le numéro client du compte de conversion Google Ads. Définissez la valeur account_type de operating_account sur GOOGLE_ADS.
developer-token en-tête de requête Aucun équivalent Un jeton de développeur n'est pas requis pour l'API Data Manager.
login-customer-id en-tête de requête login_account Définissez account_id sur le numéro client du compte de connexion. Définissez account_type sur GOOGLE_ADS si le compte de connexion est un compte Google Ads, ou sur DATA_PARTNER s'il s'agit d'un compte de partenaire de données.
linked-customer-id en-tête de requête linked_account Si vous accédez à operating_account à l'aide d'un lien partenaire, définissez account_id sur le numéro client du compte associé et account_type sur DATA_PARTNER. Sinon, ne définissez pas le champ linked_account.
conversion_action product_destination_id Définissez l'ID numérique de l'action de conversion. N'utilisez pas le nom de la ressource.

Champs d'événement

Le tableau suivant montre comment les champs d'une carte de conversion des ventes en magasin sont mappés entre les deux API.

Contrairement à l'API Google Ads, qui ne permet d'inclure qu'un seul article par transaction à l'aide de ItemAttribute, l'API Data Manager permet d'inclure plusieurs articles par événement dans CartData.

OfflineUserDataJobOperation.create (API Google Ads) Event (API Data Manager) Remarques
Aucun équivalent event_source Obligatoire : définissez la valeur sur IN_STORE pour les conversions de vente en magasin.
transaction_attribute.conversion_action destinations.product_destination_id Consultez Champs "Client" et "Action de conversion". Utilisez l'ID numérique de l'action de conversion au lieu du nom de ressource.
transaction_attribute.transaction_date_time event_timestamp
Pour en savoir plus, consultez Format du code temporel.
transaction_attribute.transaction_amount_micros
  • conversion_value (Obligatoire)
  • cart_data.items[].conversion_value
 Définissez la valeur de la devise, et non la valeur en micros. Par exemple, pour une valeur de conversion de 5,23 $, utilisez la valeur 5.23.
transaction_attribute.currency_code currency Obligatoire.
transaction_attribute.order_id transaction_id Obligatoire.
transaction_attribute.store_attribute.store_code event_location.store_id Obligatoire : définissez le code du magasin dans le champ store_id de l'objet EventLocation.
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 Mappez-le au champ value d'un CustomVariable au niveau de l'événement ou d'un ItemCustomVariable au niveau de l'article.
transaction_attribute.item_attribute.item_id cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id
  • cart_data.merchant_id
  • cart_data.items[].merchant_id
 Si vous définissez cart_data.merchant_id, il sert de valeur par défaut pour tous les articles, mais vous pouvez le remplacer pour des articles spécifiques.
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 Si vous définissez cart_data.merchant_feed_label, il sert de valeur par défaut pour tous les articles, mais vous pouvez le remplacer pour des articles spécifiques.
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 Si vous définissez cart_data.merchant_feed_language_code, il sert de valeur par défaut pour tous les articles, mais vous pouvez le remplacer pour des articles spécifiques.
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
Aucun équivalent cart_data.items[].unit_price Définissez le prix unitaire de cet article, hors taxes, frais de port et remises à portée d'événement (au niveau de la transaction).
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 Obligatoire.

third_party_user_data utilise la même structure que user_data, mais indique que les identifiants utilisateur proviennent d'une source tierce et non de données first party de l'annonceur.

Le remplissage de third_party_user_data n'est autorisé que si le compte de connexion est un partenaire de données (login_account.account_type est défini sur DATA_PARTNER).

Pour en savoir plus, consultez Champs d'identifiant utilisateur.

consent consent Les deux API utilisent un objet Consent similaire (ad_user_data, ad_personalization). Pour l'API Data Manager, vous pouvez également définir le consentement pour tous les événements d'une requête en définissant le champ consent sur IngestEventsRequest.

Champs d'identifiant utilisateur

UserIdentifier (API Google Ads) UserIdentifier (API Data Manager) Remarques
user_identifier_source

La source détermine le champ à renseigner dans l'API Data Manager Event :

  • user_data
  • third_party_user_data

third_party_user_data utilise la même structure que user_data, mais indique que les identifiants utilisateur proviennent d'une source tierce et non de données first party de l'annonceur.

Le remplissage de third_party_user_data n'est autorisé que si le compte de connexion est un partenaire de données (login_account.account_type est défini sur DATA_PARTNER).

Pour en savoir plus, consultez Champs d'identifiant utilisateur.

hashed_email email_address Définissez l'adresse e-mail mise en forme et hachée. Vous pouvez également chiffrer l'adresse e-mail hachée.
hashed_phone_number phone_number Définissez le numéro de téléphone mis en forme et haché. Vous pouvez également chiffrer le numéro de téléphone haché.
address_info address Défini sur un objet AddressInfo. Suivez les consignes de mise en forme et de hachage. Vous pouvez également chiffrer les attributs hachés d'une adresse.
address_info.hashed_first_name address.given_name
address_info.hashed_last_name address.family_name
address_info.country_code address.region_code
address_info.postal_code address.postal_code
address_info.city Aucun équivalent Non disponible dans la version actuelle de l'API Data Manager.
address_info.state Aucun équivalent Non disponible dans la version actuelle de l'API Data Manager.
address_info.hashed_street_address Aucun équivalent Non disponible dans la version actuelle de l'API Data Manager.
Précédent
Procédure de mise à jour