Importer des événements utilisateur historiques

Cette page explique comment importer des données d'événements utilisateur passés de façon groupée. Les événements utilisateur sont obligatoires pour les applications multimédias. Si vous n'utilisez pas d'applications multimédias, vous n'avez pas besoin d'importer les événements utilisateur. Toutefois, l'enregistrement des événements utilisateur est recommandé pour les applications de recherche et de recommandations personnalisées.

Pour connaître les types d'événements utilisateur que vous pouvez importer, consultez le champ eventType de l'objet userEvents. En important des événements utilisateur, vous pouvez améliorer la qualité de vos résultats. Par exemple, les événements utilisateur affectent le classement des résultats de recherche. Les résultats avec des taux de clics plus élevés sont mis en avant, tandis que ceux avec des taux de clics plus faibles sont relégués au bas de la page. N'importez que les événements utilisateur pour les documents que vous avez déjà importés dans votre data store.

Si des documents sont listés dans userEvents.Documents pour un événement, les applications d'IA associent automatiquement les événements à ce document. L'association permet aux applications d'IA d'attribuer des événements tels que les clics et les vues au bon document dans un résultat de recherche ou une recommandation. Pour les applications de recherche et de recommandations personnalisées, la jointure est asynchrone, c'est-à-dire que les événements utilisateur sont joints aux documents une fois l'importation par lot terminée (généralement en quelques minutes). Pour les applications multimédias, la jointure est synchrone. Les applications d'IA commencent à joindre les événements utilisateur aux documents pendant que l'importation par lot est toujours en cours. Pour savoir comment afficher les métriques d'événements non associés dans la console, consultez Afficher les informations agrégées concernant les événements utilisateur.

Si vous utilisez une application de recherche avec plusieurs data stores associés, importez les événements utilisateur au niveau de l'emplacement plutôt qu'au niveau du data store. Cela permet d'envoyer un événement utilisateur donné au data store auquel il est associé. Pour importer des événements utilisateur avec des documents provenant de différents dataStores au niveau de l'emplacement plutôt qu'au niveau du datastore, consultez userEvents.import.

Pour importer des événements utilisateur en temps réel, consultez Enregistrer des événements utilisateur en temps réel.

Vous pouvez importer des événements historiques de différentes manières :

Pour la représentation JSON des événements utilisateur, consultez userEvents dans la documentation de référence de l'API.

Avant de commencer

Avant d'importer des événements utilisateur :

Importer des événements utilisateur historiques depuis Cloud Storage

Si vous disposez d'une application multimédia, vous pouvez importer des événements utilisateur à l'aide de la console Google Cloud ou de l'API. Pour les autres types d'applications, vous ne pouvez importer des données qu'à l'aide de l'API.

Console

Pour importer des événements utilisateur pour les applications multimédias à l'aide de la console, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Applications d'IA.

    AI Applications

  2. Sur la page Applications, cliquez sur votre application multimédia.

  3. Accédez à la page Données.

    Pour les applications de recommandations de contenus multimédias, l'onglet Exigences affiche les documents multimédias et les événements utilisateur que vous devez importer.

  4. Cliquez sur l'onglet Événements. Si vous avez déjà importé des événements, des informations les concernant s'affichent dans cet onglet.

  5. Cliquez sur Importer des événements.

  6. Sélectionnez Cloud Storage comme source de données.

  7. Saisissez ou sélectionnez l'emplacement Cloud Storage de vos événements utilisateur.

  8. Cliquez sur Importer.

  9. L'onglet Activité affiche l'état de votre importation.

  10. Si des erreurs d'importation se produisent, dans l'onglet Activité :

    1. Développez l'erreur dans la colonne Détails, puis cliquez sur Afficher les détails pour en savoir plus dans le volet Détails du journal d'activité.

    2. Dans le volet Détails du journal d'activité, cliquez sur Afficher les journaux d'erreurs complets pour afficher l'erreur dans l'explorateur de journaux.

REST

Pour importer des événements utilisateur historiques de manière groupée depuis Cloud Storage, procédez comme suit :

  1. Créez un ou plusieurs fichiers de données pour les paramètres d'entrée de l'importation. Utilisez l'objet gcsSource pour pointer vers votre bucket Cloud Storage.

    {
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}

    Remplacez les éléments suivants :

    • INPUT_FILE : fichier Cloud Storage contenant vos données d'événements utilisateur. Assurez-vous que chaque événement utilisateur figure sur une ligne unique, sans saut de ligne. Pour la représentation JSON des événements utilisateur, consultez userEvents dans la documentation de référence de l'API. Les champs du fichier d'entrée doivent être au format suivant : gs://<bucket>/<path-to-file>/.
    • ERROR_DIRECTORY (facultatif) : Répertoire Cloud Storage contenant des informations sur les erreurs d'importation (par exemple, gs://<your-gcs-bucket>/directory/import_errors). Google recommande de laisser ce champ vide pour permettre aux applications d'IA de créer automatiquement un répertoire temporaire.

  2. Importez vos événements en envoyant une requête POST à la méthode userEvents.import, en indiquant le nom du fichier de données.

    curl -X POST \
    -v \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
    --data @DATA_FILE.json \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

    Si vous importez des événements utilisateur au niveau de l'établissement, utilisez le point de terminaison https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Importer des événements utilisateur historiques depuis BigQuery

Lorsque vous créez des tables pour les événements utilisateur dans BigQuery, utilisez les schémas décrits dans À propos des événements utilisateur.

Configurer l'accès à BigQuery

Si votre ensemble de données BigQuery se trouve dans un projet différent de celui de votre data store, suivez ces étapes pour configurer l'accès à BigQuery.

  1. Ouvrez la page IAM et administration dans la console Google Cloud .
  2. Sélectionnez le projet contenant le data store dans lequel vous souhaitez importer les événements utilisateur.
  3. Cochez la case Inclure les attributions de rôles fournies par Google.
  4. Recherchez le compte de service intitulé Compte de service Discovery Engine.
  5. Si vous n'avez pas encore lancé d'opération d'importation avec Discovery Engine, ce compte de service peut ne pas être répertorié. Si vous ne voyez pas le compte de service, revenez à la tâche d'importation et lancez l'importation. Si la tâche échoue en raison d'erreurs d'autorisation, revenez sur la page et cherchez à nouveau le compte de service. Le compte de service Discovery Engine s'affiche.
  6. Copiez l'identifiant du compte de service, qui ressemble à une adresse e-mail (par exemple, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com).
  7. Basculez vers votre projet BigQuery (sur la même page IAM et administration), puis cliquez sur Accorder l'accès.
  8. Pour Nouveaux comptes principaux, saisissez l'identifiant du compte de service et sélectionnez le rôle BigQuery > Lecteur de données BigQuery.
  9. Cliquez sur Enregistrer.

Pour en savoir plus sur l'accès à BigQuery, consultez Contrôler l'accès aux ensembles de données dans la documentation BigQuery.

Importer des événements depuis BigQuery

Si vous disposez d'une application multimédia, vous pouvez importer des événements utilisateur à l'aide de la consoleGoogle Cloud ou de l'API. Pour les autres types d'applications, vous ne pouvez importer des données qu'à l'aide de l'API.

Console

Pour importer des événements utilisateur pour les applications multimédias à l'aide de la console, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Applications d'IA.

    AI Applications

  2. Sur la page Applications, cliquez sur votre application multimédia.

  3. Accédez à la page Données.

    Pour les applications de recommandations de contenus multimédias, l'onglet Exigences affiche les documents multimédias et les événements utilisateur que vous devez importer.

  4. Cliquez sur l'onglet Événements. Si vous avez déjà importé des événements, des informations les concernant s'affichent dans cet onglet.

  5. Cliquez sur Importer des événements.

  6. Sélectionnez BigQuery comme source de données.

  7. Saisissez ou sélectionnez le chemin d'accès BigQuery pour vos événements utilisateur.

  8. Cliquez sur Importer.

  9. L'onglet Activité affiche l'état de votre importation.

  10. Si des erreurs d'importation se produisent, dans l'onglet Activité :

    1. Développez l'erreur dans la colonne Détails, puis cliquez sur Afficher les détails pour en savoir plus dans le volet Détails du journal d'activité.

    2. Dans le volet Détails du journal d'activité, cliquez sur Afficher les journaux d'erreurs complets pour afficher l'erreur dans l'explorateur de journaux.

REST

Pour importer des événements utilisateur historiques de manière groupée depuis Cloud Storage, procédez comme suit :

  1. Importez vos événements utilisateur en envoyant une requête POST à la méthode userEvents.import, en fournissant le nom du projet BigQuery, l'ID de l'ensemble de données et l'ID de la table.

    Lorsque vous importez vos événements, utilisez la valeur user_event pour dataSchema.

    curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1/projects/[PROJECT_NUMBER]/locations/global/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

    Si vous importez des événements utilisateur au niveau de l'établissement, utilisez le point de terminaison https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Importer des événements utilisateur historiques en tant que données JSON locales

Vous pouvez importer des événements utilisateur en incluant des données JSON locales pour les événements dans votre appel à la méthode userEvents.import.

Pour placer des données d'événements utilisateur dans un fichier JSON et spécifier le fichier dans une requête API, suivez ces instructions :

  1. Créez un fichier JSON contenant vos données d'événements utilisateur. Pour la représentation JSON des événements utilisateur, consultez userEvents dans la documentation de référence de l'API.

    {
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

  2. Importez vos événements en envoyant une requête POST à la méthode userEvents.import, en indiquant le nom du fichier de données.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @[JSON_FILE] \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

    Si vous importez des événements utilisateur au niveau de l'établissement, utilisez le point de terminaison https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.