Un connecteur de contenu est un logiciel permettant de balayer les données d'un dépôt d'entreprise et de remplir une source de données. Google propose les options suivantes pour développer des connecteurs de contenu:
SDK Content Connector Il s'agit d'une bonne option si vous programmez en Java. Le SDK Content Connector est un wrapper pour l'API REST qui vous permet de créer rapidement des connecteurs. Pour créer un connecteur de contenu avec le SDK, consultez l'article Créer un connecteur de contenu à l'aide du SDK Content Connector.
Une API REST de bas niveau ou des bibliothèques d'API. Utilisez ces options si vous ne programmez pas en Java, ou si votre codebase est mieux adapté à une API REST ou à une bibliothèque. Pour créer un connecteur de contenu avec l'API REST, reportez-vous à la section Créer un connecteur de contenu avec l'API REST.
Un connecteur de contenu standard exécute les tâches suivantes:
- Lit et traite les paramètres de configuration.
- Extraction de fragments distincts de données indexables, appelées éléments, à partir du dépôt de contenu tiers
- Combiner les listes de contrôle d'accès, les métadonnées et les données de contenu dans des éléments indexables.
- Indexe des éléments dans la source de données Cloud Search.
- (Facultatif) Écoute les notifications de modification du dépôt de contenu tiers. Les notifications de modification sont converties en requêtes d'indexation pour synchroniser la source de données Cloud Search avec le dépôt tiers. Le connecteur n'effectue cette tâche que si le dépôt accepte la détection des modifications.
Créer un connecteur de contenu à l'aide du SDK Content Connector
Les sections suivantes expliquent comment créer un connecteur de contenu à l'aide du SDK Content Connector.
Configurer des dépendances
Vous devez inclure certaines dépendances dans votre fichier de compilation pour utiliser le SDK. Cliquez sur un onglet ci-dessous pour afficher les dépendances de votre environnement de compilation:
Maven
<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>
Gradle
compile group: 'com.google.enterprise.cloudsearch',
name: 'google-cloudsearch-indexing-connector-sdk',
version: 'v1-0.0.3'
Créer une configuration de connecteur
Chaque connecteur dispose d'un fichier de configuration contenant ses paramètres, tels que l'ID de votre dépôt. Les paramètres sont définis sous forme de paires clé-valeur, telles que api.sourceId=1234567890abcdef
.
Le SDK Google Cloud Search contient plusieurs paramètres de configuration fournis par Google et utilisés par tous les connecteurs. Vous devez déclarer les paramètres suivants (fournis par Google) dans votre fichier de configuration:
- Pour un connecteur de contenu, vous devez déclarer
api.sourceId
etapi.serviceAccountPrivateKeyFile
, car ces paramètres identifient l'emplacement de votre dépôt et de la clé privée requise pour y accéder.
- Pour un connecteur d'identité, vous devez déclarer
api.identitySourceId
, car ce paramètre identifie l'emplacement de votre source d'identité externe. Si vous synchronisez des utilisateurs, vous devez également déclarerapi.customerId
comme ID unique du compte Google Workspace de votre entreprise.
À moins que vous ne souhaitiez remplacer les valeurs par défaut d'autres paramètres fournis par Google, vous n'avez pas besoin de les déclarer dans votre fichier de configuration. Pour en savoir plus sur les paramètres de configuration fournis par Google, comme la génération de certains ID et de certaines clés, consultez la page Paramètres de configuration fournis par Google.
Vous pouvez également définir vos propres paramètres spécifiques au dépôt à utiliser dans votre fichier de configuration.
Transmettre le fichier de configuration au connecteur
Définissez la propriété système config
pour transmettre le fichier de configuration à votre connecteur. Vous pouvez définir cette propriété à l'aide de l'argument -D
lors du démarrage du connecteur. Par exemple, la commande suivante permet de démarrer le connecteur avec le fichier de configuration MyConfig.properties
:
java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector
Si cet argument est manquant, le SDK tente d'accéder à un fichier de configuration par défaut nommé connector-config.properties
.
Déterminer votre stratégie de balayage
La fonction principale d'un connecteur de contenu consiste à balayer un dépôt et à en indexer les données. Vous devez implémenter une stratégie de balayage basée sur la taille et la disposition des données dans votre dépôt. Vous pouvez concevoir votre propre stratégie ou choisir l'une des stratégies suivantes implémentées dans le SDK:
- Stratégie de balayage complet
Une stratégie de balayage complet consiste à analyser l'intégralité du dépôt et à indexer aveuglément chaque élément. Cette stratégie est couramment utilisée lorsque vous disposez d'un petit dépôt et que vous pouvez vous permettre d'effectuer un balayage complet à chaque indexation.
Cette stratégie de balayage convient aux petits dépôts contenant principalement des données statiques et non hiérarchisées. Vous pouvez également utiliser cette stratégie de balayage lorsque la détection des modifications est difficile ou incompatible avec le dépôt.
- Stratégie de balayage de liste
La stratégie de balayage de liste consiste à analyser l'ensemble du dépôt, y compris tous les nœuds enfants, en déterminant l'état de chaque élément. Ensuite, lors d'une seconde passe, le connecteur n'indexe que les éléments nouveaux ou mis à jour depuis la dernière indexation. Cette stratégie est couramment utilisée pour effectuer des mises à jour incrémentielles d'un index existant (au lieu d'avoir à effectuer un balayage complet à chaque mise à jour de l'index).
Cette stratégie de balayage est adaptée lorsque la détection des modifications est difficile ou non prise en charge par le dépôt, que vous disposez de données non hiérarchisées et que vous travaillez avec des ensembles de données très volumineux.
- Traversée de graphe
La stratégie de balayage de graphe consiste à analyser l'intégralité du nœud parent afin de déterminer l'état de chaque élément. Ensuite, le connecteur effectue une seconde passe et n'indexe que les éléments du nœud racine qui sont nouveaux ou mis à jour depuis la dernière indexation. Enfin, le connecteur transmet tous les ID enfants, puis indexe les éléments des nœuds enfants qui sont nouveaux ou ont été mis à jour. Le connecteur poursuit ainsi de manière récursive tous les nœuds enfants jusqu'à ce que tous les éléments aient été traités. Ce balayage est généralement utilisé pour les dépôts hiérarchiques pour lesquels il n'est pas pratique de lister tous les ID.
Cette stratégie convient si vous devez explorer des données hiérarchisées, telles qu'une série de répertoires ou de pages Web.
Chacune de ces stratégies de balayage est mise en œuvre par un modèle de classe de connecteur dans le SDK. Bien que vous puissiez mettre en œuvre votre propre stratégie de balayage, ces modèles accélèrent considérablement le développement de votre connecteur. Pour créer un connecteur à partir d'un modèle, accédez à la section correspondant à votre stratégie de balayage:
- Créer un connecteur de balayage complet à partir d'un modèle de classe
- Créer un connecteur de balayage de liste à l'aide d'un modèle de classe
- Créer un connecteur de balayage de graphe à partir d'un modèle de classe
Créer un connecteur de balayage complet à partir d'un modèle de classe
Cette section fait référence aux extraits de code de l'exemple FullTraversalSample.
Implémenter le point d'entrée du connecteur
Le point d'entrée d'un connecteur est la méthode main()
. La tâche principale de cette méthode consiste à créer une instance de la classe Application
et à appeler sa méthode start()
pour exécuter le connecteur.
Avant d'appeler application.start()
, utilisez la classe IndexingApplication.Builder
pour instancier le modèle FullTraversalConnector
. Le FullTraversalConnector
accepte un objet Repository
dont vous implémentez les méthodes. L'extrait de code suivant montre comment implémenter la méthode main()
:
En arrière-plan, le SDK appelle la méthode initConfig()
une fois que la méthode main()
du connecteur a appelé Application.build
.
La méthode initConfig()
effectue les tâches suivantes:
- Il appelle la méthode
Configuation.isInitialized()
pour vérifier queConfiguration
n'a pas été initialisé. - Elle initialise un objet
Configuration
avec les paires clé/valeur fournies par Google. Chaque paire clé-valeur est stockée dans un objetConfigValue
au sein de l'objetConfiguration
.
Implémenter l'interface Repository
L'objet Repository
n'a qu'une fonction, qui consiste à balayer les éléments du dépôt et à les indexer. Lorsque vous utilisez un modèle, il vous suffit de remplacer certaines méthodes dans l'interface Repository
pour créer un connecteur de contenu. Les méthodes que vous remplacez dépendent de la stratégie de balayage et du modèle que vous utilisez. Pour FullTraversalConnector
, par exemple, vous devez remplacer les méthodes suivantes:
La méthode
init()
. Pour configurer et initialiser un dépôt de données, remplacez la méthodeinit()
.La méthode
getAllDocs()
. Pour balayer et indexer tous les éléments du dépôt de données, remplacez la méthodegetAllDocs()
. Cette méthode est appelée une fois pour chaque balayage planifié (tel que défini par votre configuration).(Facultatif) La méthode
getChanges()
. Si votre dépôt accepte la détection des modifications, remplacez la méthodegetChanges()
. Cette méthode est appelée une fois pour chaque balayage incrémentiel planifié (tel que défini par votre configuration) afin de récupérer les éléments modifiés et de les indexer.(Facultatif) La méthode
close()
. Si vous devez nettoyer le dépôt, remplacez la méthodeclose()
. Cette méthode est appelée une fois lors de l'arrêt du connecteur.
Chacune des méthodes de l'objet Repository
renvoie un objet ApiOperation
. Un objet ApiOperation
effectue une action sous la forme d'un ou de plusieurs appels IndexingService.indexItem()
pour effectuer l'indexation réelle de votre dépôt.
Obtenir les paramètres de configuration personnalisés
Dans le cadre de la gestion de la configuration de votre connecteur, vous devez récupérer les éventuels paramètres personnalisés contenus dans l'objet Configuration
. Cette tâche est généralement effectuée dans la méthode init()
d'une classe Repository
.
La classe Configuration
comporte plusieurs méthodes permettant d'obtenir différents types de données à partir d'une configuration. Chaque méthode renvoie un objet ConfigValue
. Vous utiliserez ensuite la méthode get()
de l'objet ConfigValue
pour récupérer la valeur réelle.
L'extrait de code suivant (issu de FullTraversalSample
) montre comment récupérer une seule valeur entière personnalisée à partir d'un objet Configuration
:
Pour récupérer et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration
afin d'analyser les données par fragments distincts.
L'extrait de code suivant (issu du connecteur du tutoriel) utilise la méthode getMultiValue
pour obtenir la liste des noms de dépôts GitHub:
Effectuer un balayage complet
Remplacez getAllDocs()
pour effectuer un balayage complet et indexer votre dépôt. La méthode getAllDocs()
accepte un point de contrôle. Le point de contrôle permet de reprendre l'indexation à partir d'un élément spécifique si le processus est interrompu. Pour chaque élément de votre dépôt, vous accomplirez les tâches suivantes dans la méthode getAllDocs()
:
- Définissez les autorisations.
- Définissez les métadonnées de l'élément que vous indexez.
- Combinez les métadonnées et l'élément dans une propriété
RepositoryDoc
indexable. - Empaquetez chaque élément indexable dans un itérateur renvoyé par la méthode
getAllDocs()
. Notez quegetAllDocs()
renvoie en fait unCheckpointCloseableIterable
, qui est une itération d'objetsApiOperation
, chaque objet représentant une requête API effectuée sur unRepositoryDoc
, comme l'indexation.
Si l'ensemble d'éléments est trop volumineux pour être traité via un seul appel, incluez un point de contrôle et définissez hasMore(true)
pour indiquer que davantage d'éléments sont disponibles pour l'indexation.
Définir les autorisations pour un élément
Votre dépôt s'appuie sur une liste de contrôle d'accès (LCA) pour identifier les utilisateurs ou les groupes ayant accès à un élément. Une LCA est une liste d'ID correspondant aux groupes ou aux utilisateurs autorisés à accéder à un élément.
Vous devez dupliquer la LCA utilisée par votre dépôt pour vous assurer que seuls les utilisateurs ayant accès à un élément peuvent le voir dans un résultat de recherche. La LCA d'un élément doit être incluse lors de son indexation afin que Google Cloud Search dispose des informations nécessaires pour fournir le niveau d'accès approprié à cet élément.
Le SDK Content Connector fournit un ensemble complet de classes et de méthodes de LCA pour modéliser les LCA de la plupart des dépôts. Vous devez analyser la LCA de chaque élément de votre dépôt et créer une LCA correspondante pour Google Cloud Search lorsque vous indexez un élément. Si la LCA de votre dépôt repose sur des concepts tels que l'héritage des LCA, la modélisation de cette LCA peut s'avérer délicate. Consultez la page LCA de Google Cloud Search pour en savoir plus.
Remarque:L'API Cloud Search Indexing accepte les LCA à domaine unique. Il n'est pas compatible avec les LCA interdomaines. Utilisez la classe Acl.Builder
pour définir l'accès à chaque élément à l'aide d'une LCA. L'extrait de code suivant, issu de l'exemple de balayage complet, permet à tous les utilisateurs ou "comptes principaux" (getCustomerPrincipal()
) d'être des "lecteurs" de tous les éléments (.setReaders()
) lorsqu'ils effectuent une recherche.
Vous devez maîtriser les LCA afin de les modéliser correctement pour le dépôt. Par exemple, vous indexez peut-être des fichiers dans un système de fichiers qui utilise une sorte de modèle d'héritage dans lequel les dossiers enfants héritent des autorisations des dossiers parents. La modélisation de l'héritage des LCA nécessite des informations supplémentaires. Pour en savoir plus, consultez la section LCA de Google Cloud Search.
Définir les métadonnées d'un élément
Les métadonnées sont stockées dans un objet Item
. Pour créer une Item
, vous devez disposer au minimum d'un ID de chaîne, d'un type d'élément, d'une LCA, d'une URL et d'une version uniques pour l'élément.
L'extrait de code suivant montre comment créer un Item
à l'aide de la classe d'assistance IndexingItemBuilder
.
Créer l'élément indexable
Une fois que vous avez défini les métadonnées de l'élément, vous pouvez créer l'élément indexable réel à l'aide de la classe RepositoryDoc.Builder
. L'exemple suivant montre comment créer un seul élément indexable.
Un RepositoryDoc
est un type de ApiOperation
qui exécute la requête IndexingService.indexItem()
.
Vous pouvez également utiliser la méthode setRequestMode()
de la classe RepositoryDoc.Builder
pour identifier la requête d'indexation en tant que ASYNCHRONOUS
ou SYNCHRONOUS
:
ASYNCHRONOUS
- Le mode asynchrone augmente la latence entre l'indexation et la diffusion des éléments, et autorise un débit élevé pour les requêtes d'indexation. Le mode asynchrone est recommandé pour l'indexation initiale (le remplissage) de l'ensemble du dépôt.
SYNCHRONOUS
- Le mode synchrone réduit la latence entre l'indexation et la diffusion, et accepte un quota de débit limité. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications apportées au dépôt. Si ce paramètre n'est pas spécifié, le mode de requête est défini par défaut sur
SYNCHRONOUS
.
Empaqueter chaque élément indexable dans un itérateur
La méthode getAllDocs()
renvoie un Iterator
, plus précisément un CheckpointCloseableIterable
, d'objets RepositoryDoc
. Vous pouvez utiliser la classe CheckpointClosableIterableImpl.Builder
pour créer et renvoyer un itérateur. L'extrait de code suivant montre comment construire et renvoyer un itérateur.
Le SDK exécute chaque appel d'indexation inclus dans l'itérateur.
Étapes suivantes
Voici quelques étapes que vous pouvez également suivre :
- (Facultatif) Si le débit d'indexation vous semble lent, consultez Augmenter la fréquence d'indexation pour
FullTraversalConnector
. - (Facultatif) Implémentez la méthode
close()
pour libérer toutes les ressources avant l'arrêt. - (Facultatif) Créez un connecteur d'identité à l'aide du SDK Content Connector.
Créer un connecteur de balayage de liste à partir d'un modèle de classe
La file d'attente d'indexation Cloud Search permet de conserver l'ID et la valeur de hachage facultative de chaque élément du dépôt. Un connecteur de balayage de liste place les ID d'éléments dans la file d'attente d'indexation Google Cloud Search, puis les récupère un par un en vue d'indexer les éléments. Google Cloud Search gère les files d'attente et compare leur contenu pour déterminer l'état des éléments (si un élément a été supprimé du dépôt, par exemple). Pour en savoir plus sur la file d'attente d'indexation Cloud Search, consultez l'article File d'attente d'indexation Cloud Search.
Cette section fait référence aux extraits de code de l'exemple ListTraversalSample.
Implémenter le point d'entrée du connecteur
Le point d'entrée d'un connecteur est la méthode main()
. La tâche principale de cette méthode consiste à créer une instance de la classe Application
et à appeler sa méthode start()
pour exécuter le connecteur.
Avant d'appeler application.start()
, utilisez la classe IndexingApplication.Builder
pour instancier le modèle ListingConnector
. ListingConnector
accepte un objet Repository
dont vous implémentez les méthodes. L'extrait de code suivant montre comment instancier ListingConnector
et le Repository
associé:
En arrière-plan, le SDK appelle la méthode initConfig()
une fois que la méthode main()
du connecteur a appelé Application.build
.
La méthode initConfig()
:
- Il appelle la méthode
Configuation.isInitialized()
pour vérifier queConfiguration
n'a pas été initialisé. - Elle initialise un objet
Configuration
avec les paires clé/valeur fournies par Google. Chaque paire clé-valeur est stockée dans un objetConfigValue
au sein de l'objetConfiguration
.
Implémenter l'interface Repository
L'objet Repository
n'a qu'une fonction, qui consiste à balayer les éléments du dépôt et à les indexer. Lorsque vous utilisez un modèle, il vous suffit de remplacer certaines méthodes dans l'interface Repository
pour créer un connecteur de contenu.
Les méthodes à remplacer dépendent du modèle et de la stratégie de balayage que vous utilisez. Pour ListingConnector
, par exemple, vous devez remplacer les méthodes suivantes:
La méthode
init()
. Pour configurer et initialiser un dépôt de données, remplacez la méthodeinit()
.La méthode
getIds()
. Pour récupérer les ID et les valeurs de hachage de tous les enregistrements du dépôt, remplacez la méthodegetIds()
.La méthode
getDoc()
. Pour ajouter, mettre à jour, modifier ou supprimer des éléments de l'index, remplacez la méthodegetDoc()
.(Facultatif) La méthode
getChanges()
. Si votre dépôt accepte la détection des modifications, remplacez la méthodegetChanges()
. Cette méthode est appelée une fois pour chaque balayage incrémentiel planifié (tel que défini par votre configuration) afin de récupérer les éléments modifiés et de les indexer.(Facultatif) La méthode
close()
. Si vous devez nettoyer le dépôt, remplacez la méthodeclose()
. Cette méthode est appelée une fois lors de l'arrêt du connecteur.
Chacune des méthodes de l'objet Repository
renvoie un objet ApiOperation
. Un objet ApiOperation
effectue une action sous la forme d'un ou de plusieurs appels IndexingService.indexItem()
pour effectuer l'indexation réelle de votre dépôt.
Obtenir les paramètres de configuration personnalisés
Dans le cadre de la gestion de la configuration de votre connecteur, vous devez récupérer les éventuels paramètres personnalisés contenus dans l'objet Configuration
. Cette tâche est généralement effectuée dans la méthode init()
d'une classe Repository
.
La classe Configuration
comporte plusieurs méthodes permettant d'obtenir différents types de données à partir d'une configuration. Chaque méthode renvoie un objet ConfigValue
. Vous utiliserez ensuite la méthode get()
de l'objet ConfigValue
pour récupérer la valeur réelle.
L'extrait de code suivant (issu de FullTraversalSample
) montre comment récupérer une seule valeur entière personnalisée à partir d'un objet Configuration
:
Pour récupérer et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration
afin d'analyser les données par fragments distincts.
L'extrait de code suivant (issu du connecteur du tutoriel) utilise la méthode getMultiValue
pour obtenir la liste des noms de dépôts GitHub:
Effectuer un balayage de liste
Remplacez la méthode getIds()
pour récupérer les ID et les valeurs de hachage de tous les enregistrements du dépôt.
La méthode getIds()
accepte un point de contrôle. Le point de contrôle permet de reprendre l'indexation à partir d'un élément spécifique si le processus est interrompu.
Remplacez ensuite la méthode getDoc()
pour traiter chaque élément de la file d'attente d'indexation Cloud Search.
Transmettre les ID et les valeurs de hachage des éléments
Remplacez la méthode getIds()
pour récupérer les ID des éléments et les valeurs de hachage de contenu associées dans le dépôt. Les paires ID/valeur de hachage sont ensuite empaquetées dans une requête d'opération d'envoi vers la file d'attente d'indexation Cloud Search. Les ID racine ou parents sont généralement transmis en premier, suivis des ID enfants jusqu'à ce que la hiérarchie complète des éléments ait été traitée.
La méthode getIds()
accepte un point de contrôle représentant le dernier élément à indexer. Ce point de contrôle permet de reprendre l'indexation à partir d'un élément spécifique si le processus est interrompu. Pour chaque élément du dépôt, vous accomplirez les tâches suivantes dans la méthode getIds()
:
- Récupérez l'ID de chaque élément et la valeur de hachage associée à partir du dépôt.
- Empaquetez chaque paire ID/valeur de hachage dans un
PushItems
. - Combinez chaque
PushItems
dans un itérateur renvoyé par la méthodegetIds()
. Notez quegetIds()
renvoie en fait unCheckpointCloseableIterable
, qui est une itération d'objetsApiOperation
, chaque objet représentant une requête API effectuée sur unRepositoryDoc
, par exemple pour envoyer les éléments à la file d'attente.
L'extrait de code suivant montre comment récupérer l'ID et la valeur de hachage de chaque élément, puis insérez-les dans un objet PushItems
.
Un objet PushItems
est une requête ApiOperation
visant à placer un élément dans la file d'attente d'indexation Cloud Search.
L'extrait de code suivant montre comment utiliser la classe PushItems.Builder
pour empaqueter les ID et les valeurs de hachage dans un seul élément ApiOperation
push.
Les éléments sont placés dans la file d'attente d'indexation Cloud Search en vue d'un traitement plus poussé.
Récupérer et traiter chaque élément
Remplacez getDoc()
pour traiter chaque élément de la file d'attente d'indexation Cloud Search.
Un élément peut être nouveau, modifié ou inchangé, ou n'exister plus dans le dépôt source. Récupérez et indexez chaque élément nouveau ou modifié. Supprimez de l'index les éléments qui n'existent plus dans le dépôt source.
La méthode getDoc()
accepte un élément de la file d'attente d'indexation Google Cloud Search. Pour chaque élément de la file d'attente, effectuez les étapes suivantes dans la méthode getDoc()
:
Vérifiez si l'élément figure dans le dépôt si son ID se trouve dans la file d'attente d'indexation Cloud Search. Si ce n'est pas le cas, supprimez l'élément de l'index.
Interrogez l'index pour connaître l'état de l'élément. Si un élément n'a pas changé (
ACCEPTED
), ne faites rien.Éléments modifiés ou nouveaux éléments:
- Définissez les autorisations.
- Définissez les métadonnées de l'élément que vous indexez.
- Combinez les métadonnées et l'élément dans une propriété
RepositoryDoc
indexable. - Renvoyez
RepositoryDoc
.
Remarque:Le modèle ListingConnector
ne permet pas de renvoyer null
sur la méthode getDoc()
. Le renvoi d'une null
entraîne une NullPointerException.
.
Gérer les éléments supprimés
L'extrait de code suivant montre comment déterminer si un élément existe dans le dépôt et, si ce n'est pas le cas, le supprimer.
Notez que documents
est une structure de données représentant le dépôt. Si documentID
est introuvable dans documents
, renvoyez APIOperations.deleteItem(resourceName)
pour supprimer l'élément de l'index.
Traiter les éléments non modifiés
L'extrait de code suivant montre comment interroger l'état d'un élément dans la file d'attente d'indexation Cloud Search et gérer un élément non modifié.
Pour déterminer si l'élément n'a pas été modifié, vérifiez son état ainsi que d'autres métadonnées susceptibles d'indiquer une modification. Dans cet exemple, le hachage des métadonnées permet de déterminer si l'élément a été modifié.
Définir les autorisations pour un élément
Votre dépôt s'appuie sur une liste de contrôle d'accès (LCA) pour identifier les utilisateurs ou les groupes ayant accès à un élément. Une LCA est une liste d'ID correspondant aux groupes ou aux utilisateurs autorisés à accéder à un élément.
Vous devez dupliquer la LCA utilisée par votre dépôt pour vous assurer que seuls les utilisateurs ayant accès à un élément peuvent le voir dans un résultat de recherche. La LCA d'un élément doit être incluse lors de son indexation afin que Google Cloud Search dispose des informations nécessaires pour fournir le niveau d'accès approprié à cet élément.
Le SDK Content Connector fournit un ensemble complet de classes et de méthodes de LCA pour modéliser les LCA de la plupart des dépôts. Vous devez analyser la LCA de chaque élément de votre dépôt et créer une LCA correspondante pour Google Cloud Search lorsque vous indexez un élément. Si la LCA de votre dépôt repose sur des concepts tels que l'héritage des LCA, la modélisation de cette LCA peut s'avérer délicate. Consultez la page LCA de Google Cloud Search pour en savoir plus.
Remarque:L'API Cloud Search Indexing accepte les LCA à domaine unique. Il n'est pas compatible avec les LCA interdomaines. Utilisez la classe Acl.Builder
pour définir l'accès à chaque élément à l'aide d'une LCA. L'extrait de code suivant, issu de l'exemple de balayage complet, permet à tous les utilisateurs ou "comptes principaux" (getCustomerPrincipal()
) d'être des "lecteurs" de tous les éléments (.setReaders()
) lorsqu'ils effectuent une recherche.
Vous devez maîtriser les LCA afin de les modéliser correctement pour le dépôt. Par exemple, vous indexez peut-être des fichiers dans un système de fichiers qui utilise une sorte de modèle d'héritage dans lequel les dossiers enfants héritent des autorisations des dossiers parents. La modélisation de l'héritage des LCA nécessite des informations supplémentaires. Pour en savoir plus, consultez la section LCA de Google Cloud Search.
Définir les métadonnées d'un élément
Les métadonnées sont stockées dans un objet Item
. Pour créer une Item
, vous devez disposer au minimum d'un ID de chaîne, d'un type d'élément, d'une LCA, d'une URL et d'une version uniques pour l'élément.
L'extrait de code suivant montre comment créer un Item
à l'aide de la classe d'assistance IndexingItemBuilder
.
Créer un élément indexable
Une fois que vous avez défini les métadonnées de l'élément, vous pouvez créer l'élément indexable réel à l'aide de RepositoryDoc.Builder
.
L'exemple suivant montre comment créer un seul élément indexable.
Un RepositoryDoc
est un type de ApiOperation
qui exécute la requête IndexingService.indexItem()
.
Vous pouvez également utiliser la méthode setRequestMode()
de la classe RepositoryDoc.Builder
pour identifier la requête d'indexation en tant que ASYNCHRONOUS
ou SYNCHRONOUS
:
ASYNCHRONOUS
- Le mode asynchrone augmente la latence entre l'indexation et la diffusion des éléments, et autorise un débit élevé pour les requêtes d'indexation. Le mode asynchrone est recommandé pour l'indexation initiale (le remplissage) de l'ensemble du dépôt.
SYNCHRONOUS
- Le mode synchrone réduit la latence entre l'indexation et la diffusion, et accepte un quota de débit limité. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications apportées au dépôt. Si ce paramètre n'est pas spécifié, le mode de requête est défini par défaut sur
SYNCHRONOUS
.
Étapes suivantes
Voici quelques étapes que vous pouvez également suivre :
- (Facultatif) Implémentez la méthode
close()
pour libérer toutes les ressources avant l'arrêt. - (Facultatif) Créez un connecteur d'identité à l'aide du SDK Content Connector.
Créer un connecteur de balayage de graphe à partir d'un modèle de classe
La file d'attente d'indexation Cloud Search permet de conserver l'ID et les valeurs de hachage facultatives de chaque élément du dépôt. Un connecteur de balayage de graphe place les ID d'éléments dans la file d'attente d'indexation Google Cloud Search, puis les récupère un par un en vue de leur indexation. Google Cloud Search gère les files d'attente et compare leur contenu afin de déterminer l'état des éléments (si un élément a été supprimé du dépôt, par exemple). Pour en savoir plus sur la file d'attente d'indexation Cloud Search, consultez l'article File d'attente d'indexation de Google Cloud Search.
Lors de l'indexation, le contenu des éléments est extrait du dépôt de données et tous les ID des éléments enfants sont placés dans la file d'attente. Le connecteur procède au traitement récursif des ID parents et enfants jusqu'à ce que tous les éléments soient traités.
Cette section fait référence aux extraits de code de l'exemple GraphTraversalSample.
Implémenter le point d'entrée du connecteur
Le point d'entrée d'un connecteur est la méthode main()
. La tâche principale de cette méthode consiste à créer une instance de la classe Application
et à appeler sa méthode start()
pour exécuter le connecteur.
Avant d'appeler application.start()
, utilisez la classe IndexingApplication.Builder
pour instancier le modèle ListingConnector
. Le ListingConnector
accepte un objet Repository
dont vous implémentez les méthodes.
L'extrait de code suivant montre comment instancier ListingConnector
et le Repository
associé:
En arrière-plan, le SDK appelle la méthode initConfig()
une fois que la méthode main()
du connecteur a appelé Application.build
.
La méthode initConfig()
:
- Il appelle la méthode
Configuation.isInitialized()
pour vérifier queConfiguration
n'a pas été initialisé. - Elle initialise un objet
Configuration
avec les paires clé/valeur fournies par Google. Chaque paire clé-valeur est stockée dans un objetConfigValue
au sein de l'objetConfiguration
.
Implémenter l'interface Repository
L'objet Repository
n'a qu'une fonction, qui consiste à balayer les éléments du dépôt et à les indexer. Lorsque vous utilisez un modèle, il vous suffit de remplacer certaines méthodes dans l'interface Repository
pour créer un connecteur de contenu. Les méthodes que vous remplacez dépendent du modèle et de la stratégie de balayage que vous utilisez. Pour ListingConnector
, vous remplacez les méthodes suivantes:
La méthode
init()
. Pour configurer et initialiser un dépôt de données, remplacez la méthodeinit()
.La méthode
getIds()
. Pour récupérer les ID et les valeurs de hachage de tous les enregistrements du dépôt, remplacez la méthodegetIds()
.La méthode
getDoc()
. Pour ajouter, mettre à jour, modifier ou supprimer des éléments de l'index, remplacez la méthodegetDoc()
.(Facultatif) La méthode
getChanges()
. Si votre dépôt accepte la détection des modifications, remplacez la méthodegetChanges()
. Cette méthode est appelée une fois pour chaque balayage incrémentiel planifié (tel que défini par votre configuration) afin de récupérer les éléments modifiés et de les indexer.(Facultatif) La méthode
close()
. Si vous devez nettoyer le dépôt, remplacez la méthodeclose()
. Cette méthode est appelée une fois lors de l'arrêt du connecteur.
Chacune des méthodes de l'objet Repository
renvoie un objet ApiOperation
. Un objet ApiOperation
effectue une action sous la forme d'un ou de plusieurs appels IndexingService.indexItem()
pour effectuer l'indexation réelle de votre dépôt.
Obtenir les paramètres de configuration personnalisés
Dans le cadre de la gestion de la configuration de votre connecteur, vous devez récupérer les éventuels paramètres personnalisés contenus dans l'objet Configuration
. Cette tâche est généralement effectuée dans la méthode init()
d'une classe Repository
.
La classe Configuration
comporte plusieurs méthodes permettant d'obtenir différents types de données à partir d'une configuration. Chaque méthode renvoie un objet ConfigValue
. Vous utiliserez ensuite la méthode get()
de l'objet ConfigValue
pour récupérer la valeur réelle.
L'extrait de code suivant (issu de FullTraversalSample
) montre comment récupérer une seule valeur entière personnalisée à partir d'un objet Configuration
:
Pour récupérer et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration
afin d'analyser les données par fragments distincts.
L'extrait de code suivant (issu du connecteur du tutoriel) utilise la méthode getMultiValue
pour obtenir la liste des noms de dépôts GitHub:
Effectuer un balayage de graphe
Remplacez la méthode getIds()
pour récupérer les ID et les valeurs de hachage de tous les enregistrements du dépôt.
La méthode getIds()
accepte un point de contrôle. Le point de contrôle permet de reprendre l'indexation à partir d'un élément spécifique si le processus est interrompu.
Remplacez ensuite la méthode getDoc()
pour traiter chaque élément de la file d'attente d'indexation Cloud Search.
Transmettre les ID et les valeurs de hachage des éléments
Remplacez la méthode getIds()
pour récupérer les ID des éléments et les valeurs de hachage de contenu associées dans le dépôt. Les paires ID/valeur de hachage sont ensuite empaquetées dans une requête d'opération d'envoi vers la file d'attente d'indexation Cloud Search. Les ID racine ou parents sont généralement transmis en premier, suivis des ID enfants jusqu'à ce que la hiérarchie complète des éléments ait été traitée.
La méthode getIds()
accepte un point de contrôle représentant le dernier élément à indexer. Ce point de contrôle permet de reprendre l'indexation à partir d'un élément spécifique si le processus est interrompu. Pour chaque élément du dépôt, vous accomplirez les tâches suivantes dans la méthode getIds()
:
- Récupérez l'ID de chaque élément et la valeur de hachage associée à partir du dépôt.
- Empaquetez chaque paire ID/valeur de hachage dans un
PushItems
. - Combinez chaque
PushItems
dans un itérateur renvoyé par la méthodegetIds()
. Notez quegetIds()
renvoie en fait unCheckpointCloseableIterable
, qui est une itération d'objetsApiOperation
, chaque objet représentant une requête API effectuée sur unRepositoryDoc
, par exemple pour envoyer les éléments à la file d'attente.
L'extrait de code suivant montre comment récupérer l'ID et la valeur de hachage de chaque élément, puis insérez-les dans un PushItems
. Un PushItems
est une requête ApiOperation
visant à placer un élément dans la file d'attente d'indexation Cloud Search.
L'extrait de code suivant montre comment utiliser la classe PushItems.Builder
pour empaqueter les ID et les valeurs de hachage dans une seule ApiOperation
push.
Les éléments sont placés dans la file d'attente d'indexation Cloud Search en vue d'un traitement plus poussé.
Récupérer et traiter chaque élément
Remplacez getDoc()
pour traiter chaque élément de la file d'attente d'indexation Cloud Search.
Un élément peut être nouveau, modifié ou inchangé, ou n'exister plus dans le dépôt source. Récupérez et indexez chaque élément nouveau ou modifié. Supprimez de l'index les éléments qui n'existent plus dans le dépôt source.
La méthode getDoc()
accepte un élément de la file d'attente d'indexation Cloud Search. Pour chaque élément de la file d'attente, effectuez les étapes suivantes dans la méthode getDoc()
:
Vérifiez si l'élément figure dans le dépôt, dans la file d'attente d'indexation Cloud Search. Si ce n'est pas le cas, supprimez l'élément de l'index. Si l'élément existe, passez à l'étape suivante.
Éléments modifiés ou nouveaux éléments:
- Définissez les autorisations.
- Définissez les métadonnées de l'élément que vous indexez.
- Combinez les métadonnées et l'élément dans une propriété
RepositoryDoc
indexable. - Placez les ID des éléments enfants dans la file d'attente d'indexation Cloud Search pour un traitement ultérieur.
- Renvoyez
RepositoryDoc
.
Gérer les éléments supprimés
L'extrait de code suivant montre comment déterminer si un élément existe dans l'index et, s'il ne l'est pas, comment le supprimer.
Définir les autorisations pour un élément
Votre dépôt s'appuie sur une liste de contrôle d'accès (LCA) pour identifier les utilisateurs ou les groupes ayant accès à un élément. Une LCA est une liste d'ID correspondant aux groupes ou aux utilisateurs autorisés à accéder à un élément.
Vous devez dupliquer la LCA utilisée par votre dépôt pour vous assurer que seuls les utilisateurs ayant accès à un élément peuvent le voir dans un résultat de recherche. La LCA d'un élément doit être incluse lors de son indexation afin que Google Cloud Search dispose des informations nécessaires pour fournir le niveau d'accès approprié à cet élément.
Le SDK Content Connector fournit un ensemble complet de classes et de méthodes de LCA pour modéliser les LCA de la plupart des dépôts. Vous devez analyser la LCA de chaque élément de votre dépôt et créer une LCA correspondante pour Google Cloud Search lorsque vous indexez un élément. Si la LCA de votre dépôt repose sur des concepts tels que l'héritage des LCA, la modélisation de cette LCA peut s'avérer délicate. Consultez la page LCA de Google Cloud Search pour en savoir plus.
Remarque:L'API Cloud Search Indexing accepte les LCA à domaine unique. Il n'est pas compatible avec les LCA interdomaines. Utilisez la classe Acl.Builder
pour définir l'accès à chaque élément à l'aide d'une LCA. L'extrait de code suivant, issu de l'exemple de balayage complet, permet à tous les utilisateurs ou "comptes principaux" (getCustomerPrincipal()
) d'être des "lecteurs" de tous les éléments (.setReaders()
) lorsqu'ils effectuent une recherche.
Vous devez maîtriser les LCA afin de les modéliser correctement pour le dépôt. Par exemple, vous indexez peut-être des fichiers dans un système de fichiers qui utilise une sorte de modèle d'héritage dans lequel les dossiers enfants héritent des autorisations des dossiers parents. La modélisation de l'héritage des LCA nécessite des informations supplémentaires. Pour en savoir plus, consultez la section LCA de Google Cloud Search.
Définir les métadonnées d'un élément
Les métadonnées sont stockées dans un objet Item
. Pour créer une Item
, vous devez disposer au minimum d'un ID de chaîne, d'un type d'élément, d'une LCA, d'une URL et d'une version uniques pour l'élément.
L'extrait de code suivant montre comment créer un Item
à l'aide de la classe d'assistance IndexingItemBuilder
.
Créer l'élément indexable
Une fois que vous avez défini les métadonnées de l'élément, vous pouvez créer l'élément indexable réel à l'aide de RepositoryDoc.Builder
.
L'exemple suivant montre comment créer un seul élément indexable.
Un RepositoryDoc
est un type de ApiOperation
qui exécute la requête IndexingService.indexItem()
.
Vous pouvez également utiliser la méthode setRequestMode()
de la classe RepositoryDoc.Builder
pour identifier la requête d'indexation en tant que ASYNCHRONOUS
ou SYNCHRONOUS
:
ASYNCHRONOUS
- Le mode asynchrone augmente la latence entre l'indexation et la diffusion des éléments, et autorise un débit élevé pour les requêtes d'indexation. Le mode asynchrone est recommandé pour l'indexation initiale (le remplissage) de l'ensemble du dépôt.
SYNCHRONOUS
- Le mode synchrone réduit la latence entre l'indexation et la diffusion, et accepte un quota de débit limité. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications apportées au dépôt. Si ce paramètre n'est pas spécifié, le mode de requête est défini par défaut sur
SYNCHRONOUS
.
Placer les ID des éléments enfants dans la file d'attente d'indexation Cloud Search
L'extrait de code suivant montre comment inclure les ID enfants de l'élément parent en cours de traitement dans la file d'attente pour traitement. Ces ID sont traités après l'indexation de l'élément parent.
Étapes suivantes
Voici quelques étapes que vous pouvez également suivre :
- (Facultatif) Implémentez la méthode
close()
pour libérer toutes les ressources avant l'arrêt. - (Facultatif) Créez un connecteur d'identité à l'aide du SDK Identity Connector.
Créer un connecteur de contenu à l'aide de l'API REST
Les sections suivantes expliquent comment créer un connecteur de contenu à l'aide de l'API REST.
Déterminer votre stratégie de balayage
La fonction principale d'un connecteur de contenu consiste à balayer un dépôt et à en indexer les données. Vous devez implémenter une stratégie de balayage basée sur la taille et la disposition des données dans votre dépôt. Voici trois stratégies de balayage courantes:
- Stratégie de balayage complet
Une stratégie de balayage complet consiste à analyser l'intégralité du dépôt et à indexer aveuglément chaque élément. Cette stratégie est couramment utilisée lorsque vous disposez d'un petit dépôt et que vous pouvez vous permettre d'effectuer un balayage complet à chaque indexation.
Cette stratégie de balayage convient aux petits dépôts contenant principalement des données statiques et non hiérarchisées. Vous pouvez également utiliser cette stratégie de balayage lorsque la détection des modifications est difficile ou incompatible avec le dépôt.
- Stratégie de balayage de liste
La stratégie de balayage de liste consiste à analyser l'ensemble du dépôt, y compris tous les nœuds enfants, en déterminant l'état de chaque élément. Ensuite, lors d'une seconde passe, le connecteur n'indexe que les éléments nouveaux ou mis à jour depuis la dernière indexation. Cette stratégie est couramment utilisée pour effectuer des mises à jour incrémentielles d'un index existant (au lieu d'avoir à effectuer un balayage complet à chaque mise à jour de l'index).
Cette stratégie de balayage est adaptée lorsque la détection des modifications est difficile ou non prise en charge par le dépôt, que vous disposez de données non hiérarchisées et que vous travaillez avec des ensembles de données très volumineux.
- Traversée de graphe
La stratégie de balayage de graphe consiste à analyser l'intégralité du nœud parent afin de déterminer l'état de chaque élément. Ensuite, le connecteur effectue une seconde passe et n'indexe que les éléments du nœud racine qui sont nouveaux ou mis à jour depuis la dernière indexation. Enfin, le connecteur transmet tous les ID enfants, puis indexe les éléments des nœuds enfants qui sont nouveaux ou ont été mis à jour. Le connecteur poursuit ainsi de manière récursive tous les nœuds enfants jusqu'à ce que tous les éléments aient été traités. Ce balayage est généralement utilisé pour les dépôts hiérarchiques pour lesquels il n'est pas pratique de lister tous les ID.
Cette stratégie convient si vous devez explorer des données hiérarchisées, telles qu'une série de répertoires ou de pages Web.
Implémenter votre stratégie de balayage et vos éléments d'index
Chaque élément indexable pour Cloud Search est appelé élément dans l'API Cloud Search. Un élément peut être un fichier, un dossier, une ligne d'un fichier CSV ou un enregistrement de base de données.
Une fois le schéma enregistré, vous pouvez renseigner l'index en:
(Facultatif) Utilisation de
items.upload
pour importer des fichiers de plus de 100 Kio à indexer. Pour les fichiers plus petits, intégrez le contenu en tant que inlineContent avecitems.index
.(Facultatif) Utilisez
media.upload
pour importer des fichiers multimédias à indexer.Utilisation de
items.index
pour indexer l'élément Par exemple, si votre schéma utilise la définition d'objet dans le schéma de film, une requête d'indexation pour un seul élément se présente comme suit:{ "name": "datasource/<data_source_id>/items/titanic", "acl": { "readers": [ { "gsuitePrincipal": { "gsuiteDomain": true } } ] }, "metadata": { "title": "Titanic", "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1", "objectType": "movie" }, "structuredData": { "object": { "properties": [ { "name": "movieTitle", "textValues": { "values": [ "Titanic" ] } }, { "name": "releaseDate", "dateValues": { "values": [ { "year": 1997, "month": 12, "day": 19 } ] } }, { "name": "actorName", "textValues": { "values": [ "Leonardo DiCaprio", "Kate Winslet", "Billy Zane" ] } }, { "name": "genre", "enumValues": { "values": [ "Drama", "Action" ] } }, { "name": "userRating", "integerValues": { "values": [ 8 ] } }, { "name": "mpaaRating", "textValues": { "values": [ "PG-13" ] } }, { "name": "duration", "textValues": { "values": [ "3 h 14 min" ] } } ] } }, "content": { "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.", "contentFormat": "TEXT" }, "version": "01", "itemType": "CONTENT_ITEM" }
(Facultatif) Utilisez des appels items.get pour vérifier qu'un élément a été indexé.
Pour effectuer un balayage complet, vous devez régulièrement réindexer l'ensemble du dépôt. Pour effectuer un balayage de liste ou de graphe, vous devez ajouter du code permettant de gérer les modifications du dépôt.
Gérer les modifications du dépôt
Vous pouvez collecter et indexer régulièrement chaque élément d'un dépôt pour effectuer une indexation complète. Bien qu'elle soit efficace pour garantir la mise à jour de votre index, une indexation complète peut s'avérer coûteuse dans le cas de dépôts plus vastes ou hiérarchisés.
Au lieu d'utiliser de temps en temps des appels d'index pour indexer un dépôt entier, vous pouvez utiliser la file d'attente d'indexation Google Cloud comme mécanisme de suivi des modifications et pour indexer uniquement les éléments qui ont changé. Utilisez les requêtes items.push pour placer des éléments dans la file d'attente en vue d'une interrogation et d'une mise à jour ultérieures. Consultez l'article File d'attente d'indexation Google Cloud pour en savoir plus.
Pour en savoir plus sur l'API Google Cloud Search, consultez la page API Cloud Search.