Cette page a été traduite par l'API Cloud Translation.

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 requis pour les recommandations de contenus multimédias. Si vous n'utilisez pas de médias des recommandations, il n'est pas nécessaire d'importer des événements utilisateur. Toutefois, il est recommandé pour les applications de recherche de contenus multimédias.

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 recommandations et le classement de vos résultats de recherche. Les résultats de recherche affichant les taux de clics les plus élevés sont boostés, tandis que ceux affichant des taux de clics plus élevés des taux de clics plus faibles sont perdus. N'importez pas d'événements utilisateur pour les documents que vous n'avez pas encore importés.

Si un événement comporte des documents listés dans userEvents.Documents, alors Vertex AI Search joint automatiquement les événements à ce document. L'association permet à Vertex AI Search 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 mots clés génériques la jointure s'effectue de manière asynchrone, c'est-à-dire que les événements utilisateur sont associés aux documents une fois l'importation par lots terminée (ce qui se produit généralement dans minutes). Pour les applications multimédias, l'association se produit de manière synchrone. Vertex AI Search commence à associer les événements utilisateur aux documents pendant que l'importation par lot est en cours. Pour savoir comment afficher les métriques d'événements non associés la console, consultez Affichez les informations agrégées sur les événements utilisateur.

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

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

Depuis Cloud Storage
Depuis BigQuery
En tant que données JSON locales

Pour connaître 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:

Créez un data store et une application.
Consultez la section À propos des événements utilisateur pour connaître les exigences concernant les événements utilisateur.

Importer l'historique des événements utilisateur 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 à l'aide de l'API.

Console

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

Dans la console Google Cloud, accédez à la page Agent Builder.

Agent Builder
Sur la page Applications, cliquez sur votre application multimédia.
Accédez à la page Données.

Pour les applications de recommandations de contenus multimédias, l'onglet Conditions requises affiche les contenus des documents et des événements utilisateur à importer.
Cliquez sur l'onglet Événements. Si vous avez déjà importé des événements, s'affichent dans cet onglet.
Cliquez sur Importer des événements.
Sélectionnez Cloud Storage comme source de données.
Saisissez ou sélectionnez l'emplacement Cloud Storage de vos événements utilisateur.
Cliquez sur Importer.
L'onglet Activité affiche l'état de l'importation.
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 afficher plus d'informations dans le volet Détails du journal des activités.
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 un historique d'événements utilisateur de manière groupée à partir de Cloud Storage, procédez comme suit :

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"
  }
}
```
- INPUT_FILE: fichier Cloud Storage contenant votre utilisateur les données d'événement. Assurez-vous que chaque événement utilisateur figure sur une ligne unique, sans saut de ligne. Pour connaître 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. Un répertoire Cloud Storage contenant des informations sur les erreurs d'importation (par exemple, gs://<your-gcs-bucket>/directory/import_errors). Ce que Google recommande Laissez ce champ vide pour permettre à Vertex AI Agent Builder de créer automatiquement un répertoire temporaire.

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

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

Importer l'historique des événements utilisateur depuis BigQuery

Lorsque vous créez des tables pour des événements utilisateur dans BigQuery, utilisez les schémas décrits dans la section À 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 votre entrepôt de données, procédez comme suit pour configurer l'accès à BigQuery.

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

Pour en savoir plus sur l'accès à BigQuery, consultez la section 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 console Google Cloud ou l'API. Pour les autres types d'applications, vous ne pouvez importer les données qu'à l'aide de API.

Console

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

Dans la console Google Cloud, accédez à la page Agent Builder.

Agent Builder
Sur la page Applications, cliquez sur votre application multimédia.
Accédez à la page Données.

Pour les applications de recommandations de contenus multimédias, l'onglet Conditions requises affiche les contenus des documents et des événements utilisateur à importer.
Cliquez sur l'onglet Événements. Si vous avez déjà importé des événements, s'affichent dans cet onglet.
Cliquez sur Importer des événements.
Sélectionnez BigQuery comme source de données.
Saisissez ou sélectionnez le chemin d'accès BigQuery de vos événements utilisateur.
Cliquez sur Importer.
L'onglet Activité affiche l'état de l'importation.
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 afficher plus d'informations dans le volet Détails du journal des activités.
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 de façon groupée des événements utilisateur historiques depuis Cloud Storage, procédez comme suit : étapes:

Importez vos événements utilisateur en envoyant une requête POST à la méthode userEvents:import, en indiquant 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.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/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"
      }
    }'

Importer un historique d'événements utilisateur 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 les données d'événement utilisateur dans un fichier JSON et le spécifier dans une requête API, procédez comme suit:

Créez un fichier JSON contenant vos données d'événements utilisateur. Pour connaître 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
      }
    ]
  }
}
```

Importez vos événements en envoyant une requête POST à userEvents:import, en indiquant le nom de la 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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"