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.

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 ont une incidence sur le classement des résultats de recherche. Les résultats ayant des taux de clics plus élevés sont mis en avant, tandis que ceux ayant des taux de clics plus faibles sont relégués au second plan. N'importez que les événements utilisateur pour les documents que vous avez déjà importés dans votre data store.

Si un événement comporte des documents listés dans userEvents.Documents, Gemini Enterprise associe automatiquement les événements à ce document. La jointure permet à Gemini Enterprise d'attribuer des événements tels que des clics et des 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 se produit de manière 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).

Si vous utilisez une application de recherche à laquelle plusieurs datastores sont associés, importez les événements utilisateur au niveau de l'emplacement plutôt qu'au niveau du datastore. Cela permet d'envoyer un événement utilisateur donné au data store auquel il est associé. Lorsque vous importez des événements utilisateur au niveau d'un emplacement, incluez le champ engine dans l'événement utilisateur pour l'associer à l'application appropriée. Pour obtenir des exemples d'événements utilisateur incluant le champ engine, consultez les pages suivantes :

Pour en savoir plus sur la méthode d'importation, 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 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 :

Importer l'historique des événements utilisateur depuis Cloud Storage

REST

Pour importer de manière groupée des événements utilisateur historiques 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 dans Cloud Storage contenant vos données d'événements utilisateur. Assurez-vous que chaque événement utilisateur se trouve sur une seule ligne, sans saut de ligne. Pour obtenir 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 pour les informations d'erreur concernant l'importation, par exemple gs://<your-gcs-bucket>/directory/import_errors. Google recommande de laisser ce champ vide pour permettre à Gemini Enterprise 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/userEvents:import"
    

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

Lorsque vous créez des tables pour les événements utilisateur dans BigQuery, utilisez les schémas documentés dans À propos des événements utilisateur pour les applications personnalisées. Chaque événement utilisateur search doit inclure un champ engine pour associer l'événement à une application. Pour en savoir plus, consultez engine.

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 nommé 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 n'est peut-être pas listé. Si vous ne voyez pas ce compte de service, revenez à la tâche d'importation et lancez l'importation. En cas d'échec dû à des erreurs d'autorisation, revenez ici et effectuez cette tâche. 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.).
  7. Accédez à votre projet BigQuery (sur la même page IAM et administration), puis cliquez sur Accorder l'accès.
  8. Dans le champ Nouveaux comptes principaux, saisissez l'identifiant du compte de service, puis 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

REST

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

  1. 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.

    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/userEvents:import" \
      --data '{
          "bigquerySource": {
              "projectId":"PROJECT_ID",
              "datasetId": "DATASET_ID",
              "tableId": "TABLE_ID",
              "dataSchema": "user_event"
          }
        }'
    

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

  1. Créez un fichier JSON contenant vos données d'événement utilisateur. Pour obtenir 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/userEvents:import"