Un connecteur de contenu est un programme logiciel qui permet de parcourir les données d'un dépôt d'entreprise et de les remplir. Google propose les options suivantes pour développer des connecteurs de contenu:
SDK Content Connector Cette option est 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 à l'aide du 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 convient mieux à une API REST ou à une bibliothèque. Pour créer un connecteur de contenu à l'aide de l'API REST, reportez-vous à la section Créer un connecteur de contenu à l'aide de l'API REST.
Un connecteur de contenu type effectue les tâches suivantes:
- Lit et traite les paramètres de configuration.
- Extrait des fragments de données indexables distincts, appelés éléments, à partir du dépôt de contenu tiers.
- Combine les LCA, les métadonnées et les données de contenu pour créer 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 afin que la source de données Cloud Search soit synchronisée avec le dépôt tiers. Le connecteur n'exécute cette tâche que si le dépôt est compatible avec 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 les 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 la configuration d'un connecteur
Chaque connecteur dispose d'un fichier de configuration contenant les paramètres utilisés par le connecteur, tels que l'ID de votre dépôt. Les paramètres sont définis sous forme de paires valeur/clé, par exemple 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 la clé privée nécessaire 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 pour le compte Google Workspace de votre entreprise.
À moins que vous ne souhaitiez remplacer les valeurs par défaut des 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, tels que la génération de certains ID et clés, consultez la section 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 la propriété à l'aide de l'argument -D
lors du démarrage du connecteur. Par exemple, la commande suivante démarre 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 à traverser un dépôt et à indexer ses données. Vous devez mettre en œuvre 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 mises en œuvre dans le SDK:
- Stratégie de balayage complet
Une stratégie de balayage complet analyse l'intégralité du dépôt et indexe aveuglement 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 est adaptée aux petits dépôts contenant principalement des données statiques et non hiérarchiques. Vous pouvez également utiliser cette stratégie de balayage lorsque la détection des modifications est difficile ou incompatible avec le dépôt.
- Liste des stratégies de balayage
Une stratégie de balayage de liste permet d'analyser l'ensemble du dépôt, y compris tous les nœuds enfants, en déterminant l'état de chaque élément. Ensuite, le connecteur procède à une deuxième passe et 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 sur un index existant (plutôt que 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 incompatible avec le dépôt, que vous disposez de données non hiérarchiques et que vous travaillez avec des ensembles de données très volumineux.
- Traversée de graphique
Une stratégie de balayage de graphe analyse l'intégralité du nœud parent en déterminant l'état de chaque élément. Ensuite, le connecteur procède à une deuxième passe et seuls les éléments d'index du nœud racine sont nouveaux ou mis à jour depuis la dernière indexation. Enfin, le connecteur transmet les ID enfants, puis indexe les éléments des nœuds enfants qui sont nouveaux ou mis à jour. Le connecteur continue de manière récursive via tous les nœuds enfants jusqu'à ce que tous les éléments aient été traités. Ce parcours est généralement utilisé pour les dépôts hiérarchiques pour lesquels il n'est pas possible de répertorier tous les ID.
Cette stratégie est adaptée si vous devez explorer des données hiérarchiques, telles qu'une série de répertoires ou de pages Web.
Chacune de ces stratégies de balayage est mise en œuvre par une classe de connecteur de modèle 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 à l'aide d'un modèle, accédez à la section correspondant à votre stratégie de balayage:
- Créer un connecteur de balayage complet à l'aide d'un modèle de classe
- Créer un connecteur de balayage de liste à l'aide d'une classe de modèle
- Créer un connecteur de balayage de graphe à l'aide d'une classe de modèle
Créer un connecteur de balayage complet à l'aide d'une classe de modèle
Cette section fait référence aux extraits de code de l'exemple FullTraversalSample.
Mettre en œuvre 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 l'objet FullTraversalConnector
. Le FullTraversalConnector
accepte un objet Repository
dont vous mettez en œuvre les méthodes. L'extrait de code suivant montre comment mettre en œuvre la méthode main()
:
En arrière-plan, le SDK appelle la méthode initConfig()
après l'appel de la méthode main()
de votre connecteur Application.build
.
La méthode initConfig()
accomplit les tâches suivantes:
- Il appelle la méthode
Configuation.isInitialized()
pour s'assurer que leConfiguration
n'a pas été initialisé. - 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
La seule fonction de l'objet Repository
est d'effectuer le balayage et l'indexation des éléments du dépôt. 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 la méthode FullTraversalConnector
, 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
getAllDocs()
. Pour traverser et indexer tous les éléments du dépôt de données, ignorez la méthodegetAllDocs()
. Cette méthode est appelée une fois pour chaque balayage planifié (tel que défini par votre configuration).(Facultatif) Méthode
getChanges()
. Si votre dépôt est compatible avec 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) Méthode
close()
. Si vous devez effectuer un nettoyage du dépôt, ignorez 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 type d'objet ApiOperation
. Un objet ApiOperation
effectue une action sous la forme d'un seul appel, voire de plusieurs, IndexingService.indexItem()
pour effectuer l'indexation réelle de votre dépôt.
Obtenir des paramètres de configuration personnalisés
Dans le cadre de la configuration de votre connecteur, vous devez récupérer tous les paramètres personnalisés de l'objet Configuration
. Cette tâche est généralement effectuée dans la méthode init()
d'une classe Repository
.
La classe Configuration
dispose de 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 suivant, de FullTraversalSample
, montre comment récupérer un seul nombre entier personnalisé à partir d'un objet Configuration
:
Pour obtenir et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration
pour analyser les données en fragments discrets.
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 d'un élément spécifique en cas d'interruption du processus. Pour chaque élément du dépôt, procédez comme suit 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 en un seul élément
RepositoryDoc
indexable. - Empaqueter chaque élément indexable dans un itérateur renvoyé par la méthode
getAllDocs()
Notez quegetAllDocs()
renvoie en fait uneCheckpointCloseableIterable
, qui est une itération d'objetsApiOperation
. chaque objet représentant une requête API effectuée sur une ressourceRepositoryDoc
, telle que l'indexation.
Si l'ensemble d'éléments est trop volumineux pour être traité en 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 d'un élément
Votre dépôt identifie les utilisateurs ou les groupes ayant accès à un élément à l'aide d'une liste de contrôle d'accès (LCA). Une LCA est une liste d'ID correspondant à des groupes ou des utilisateurs pouvant accéder à l'é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 puissent le voir dans un résultat de recherche. La LCA d'un élément doit être incluse lors de l'indexation d'un élément afin que Google Cloud Search dispose des informations nécessaires pour fournir le niveau d'accès approprié à l'élément.
Le SDK Content Connector propose un grand nombre de méthodes et de classes ACL 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 emploie des concepts tels que l'héritage des LCA, la modélisation de cette LCA peut s'avérer délicate. Pour plus d'informations sur les LCA Google Cloud, consultez la page Listes de contrôle d'accès Google Cloud Search.
Remarque:L'API Cloud Search Indexing accepte les LCA à domaine unique. Il ne prend pas en charge 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 "principals" (getCustomerPrincipal()
) d'être des "lecteurs" de tous les éléments (.setReaders()
) lors d'une recherche ;
Vous devez comprendre les LCA pour modéliser correctement les LCA du dépôt. Par exemple, vous indexez peut-être les fichiers d'un système de fichiers qui utilise un modèle d'héritage selon 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 détaillées dans les 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 un Item
, vous devez disposer au minimum d'un ID de chaîne unique, d'un type d'élément, d'une LCA, d'une URL et d'une version de 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 celui-ci à l'aide de la classe RepositoryDoc.Builder
. L'exemple suivant montre comment créer un élément indexable unique.
Un RepositoryDoc
est un type de ApiOperation
qui effectue la requête IndexingService.indexItem()
réelle.
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 de l'indexation vers le temps de diffusion et gère un quota de débit élevé pour les requêtes d'indexation. Le mode asynchrone est recommandé pour l'indexation initiale (remplissage) de l'ensemble du dépôt.
SYNCHRONOUS
- Le mode synchrone a pour effet de réduire la latence d'indexation vers la diffusion et de limiter le quota de débit. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications du dépôt. S'il n'est pas spécifié, le mode de requête par défaut est
SYNCHRONOUS
.
Empaqueter chaque élément indexable d'un itérateur
La méthode getAllDocs()
renvoie un élément Iterator
, plus précisément un CheckpointCloseableIterable
, de RepositoryDoc
. Vous pouvez utiliser la classe CheckpointClosableIterableImpl.Builder
pour créer et renvoyer un itérateur. L'extrait de code suivant montre comment créer 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 votre débit d'indexation semble lent, consultez la section Augmenter le taux d'indexation de
FullTraversalConnector
. - (Facultatif) Mettez en œuvre 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 à l'aide d'une classe de modèle
La file d'attente d'indexation Cloud Search contient les ID et les valeurs de hachage facultatives pour chaque élément du dépôt. Un connecteur de balayage de liste transfère les ID d'élément à la file d'attente d'indexation Google Cloud Search et les récupère un par un pour les indexer. Google Cloud Search gère les files d'attente et compare leur contenu pour déterminer leur état, par exemple si un élément a été supprimé du dépôt. Pour plus d'informations sur la file d'attente d'indexation Cloud Search, consultez la page File d'attente d'indexation Google Cloud Search.
Cette section fait référence aux extraits de code de l'exemple ListTraversalSample.
Mettre en œuvre 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 l'objet ListingConnector
. Le ListingConnector
accepte un objet Repository
dont vous mettez en œuvre les méthodes. L'extrait de code suivant montre comment instancier la ListingConnector
et sa Repository
associée:
En arrière-plan, le SDK appelle la méthode initConfig()
après l'appel de la méthode main()
de votre connecteur Application.build
.
Méthode initConfig()
:
- Il appelle la méthode
Configuation.isInitialized()
pour s'assurer que leConfiguration
n'a pas été initialisé. - 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
La seule fonction de l'objet Repository
est d'effectuer le balayage et l'indexation des éléments du dépôt. 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 la méthode ListingConnector
, remplacez les méthodes suivantes:
La méthode
init()
. Pour configurer et initialiser un dépôt de données, remplacez la méthodeinit()
.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()
.Méthode
getDoc()
. Pour ajouter, mettre à jour, modifier ou supprimer des éléments de l'index, ignorez la méthodegetDoc()
.(Facultatif) Méthode
getChanges()
. Si votre dépôt est compatible avec 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) Méthode
close()
. Si vous devez effectuer un nettoyage du dépôt, ignorez 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 type d'objet ApiOperation
. Un objet ApiOperation
effectue une action sous la forme d'un seul appel, voire de plusieurs, IndexingService.indexItem()
pour effectuer l'indexation réelle de votre dépôt.
Obtenir des paramètres de configuration personnalisés
Dans le cadre de la configuration de votre connecteur, vous devez récupérer tous les paramètres personnalisés de l'objet Configuration
. Cette tâche est généralement effectuée dans la méthode init()
d'une classe Repository
.
La classe Configuration
dispose de 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 suivant, de FullTraversalSample
, montre comment récupérer un seul nombre entier personnalisé à partir d'un objet Configuration
:
Pour obtenir et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration
pour analyser les données en fragments discrets.
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:
Balayage de la 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 au niveau d'un élément spécifique en cas d'interruption du processus.
Remplacez ensuite la méthode getDoc()
pour gérer chaque élément de la file d'attente d'indexation Cloud Search.
ID d'élément push et valeurs de hachage
Ignorez getIds()
pour récupérer les ID d'éléments et les valeurs de hachage de contenu associées dans le dépôt. Les paires d'ID et de 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 parent sont généralement transférés en premier, suivis des ID des enfants, jusqu'à ce que l'ensemble de la hiérarchie des éléments ait été traitée.
La méthode getIds()
accepte un point de contrôle représentant le dernier élément à indexer. Le point de contrôle peut être utilisé pour reprendre l'indexation d'un élément spécifique en cas d'interruption du processus. Pour chaque élément du dépôt, procédez comme suit dans la méthode getIds()
:
- Récupérez l'ID de chaque élément et la valeur de hachage associée dans le dépôt.
- Empaquetez chaque paire ID/valeur de hachage dans un élément
PushItems
. - Combinez chaque valeur
PushItems
dans un itérateur renvoyé par la méthodegetIds()
. Notez quegetIds()
renvoie en fait uneCheckpointCloseableIterable
, qui est une itération d'objetsApiOperation
. chaque objet représentant une requête API effectuée sur unRepositoryDoc
, tel que le transfert des éléments vers la file d'attente.
L'extrait de code suivant montre comment obtenir l'ID et la valeur de hachage de chaque élément, et les insérer dans un élément PushItems
.
Une requête PushItems
est une requête ApiOperation
qui consiste à envoyer un élément à 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 en une seule opération ApiOperation
.
Les éléments sont placés dans la file d'attente d'indexation Cloud Search en vue d'un traitement ultérieur.
Récupérer et gérer chaque élément
Ignorez getDoc()
pour gérer chaque élément de la file d'attente d'indexation Cloud Search.
Un élément peut être nouveau, modifié ou inchangé, ou ne peut plus exister dans le dépôt source. Récupérez et indexez chaque élément nouveau ou modifié. Supprimez les éléments de l'index 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, procédez comme suit dans la méthode getDoc()
:
Vérifiez si l'ID de l'élément, dans la file d'attente d'indexation Cloud Search, existe dans le dépôt. Si ce n'est pas le cas, supprimez-le de l'index.
Interrogez l'index pour connaître l'état de l'élément. Si celui-ci n'est pas modifié (
ACCEPTED
), ne faites rien.Index modifié 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 en un seul élément
RepositoryDoc
indexable. - Renvoyez
RepositoryDoc
.
Remarque:Le modèle ListingConnector
ne permet pas de renvoyer null
sur la méthode getDoc()
. Le renvoi de null
génère 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.
Gérer les éléments non modifiés
L'extrait de code suivant indique comment interroger l'état d'un élément dans la file d'attente d'indexation Cloud Search et comment gérer un élément non modifié.
Pour déterminer si un élément n'a pas été modifié, vérifiez son état, ainsi que d'autres métadonnées susceptibles d'indiquer une modification. Dans l'exemple, le hachage des métadonnées est utilisé pour déterminer si l'élément a été modifié.
Définir les autorisations d'un élément
Votre dépôt identifie les utilisateurs ou les groupes ayant accès à un élément à l'aide d'une liste de contrôle d'accès (LCA). Une LCA est une liste d'ID correspondant à des groupes ou des utilisateurs pouvant accéder à l'é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 puissent le voir dans un résultat de recherche. La LCA d'un élément doit être incluse lors de l'indexation d'un élément afin que Google Cloud Search dispose des informations nécessaires pour fournir le niveau d'accès approprié à l'élément.
Le SDK Content Connector propose un grand nombre de méthodes et de classes ACL 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 emploie des concepts tels que l'héritage des LCA, la modélisation de cette LCA peut s'avérer délicate. Pour plus d'informations sur les LCA Google Cloud, consultez la page Listes de contrôle d'accès Google Cloud Search.
Remarque:L'API Cloud Search Indexing accepte les LCA à domaine unique. Il ne prend pas en charge 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 "principals" (getCustomerPrincipal()
) d'être des "lecteurs" de tous les éléments (.setReaders()
) lors d'une recherche ;
Vous devez comprendre les LCA pour modéliser correctement les LCA du dépôt. Par exemple, vous indexez peut-être les fichiers d'un système de fichiers qui utilise un modèle d'héritage selon 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 détaillées dans les 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 un Item
, vous devez disposer au minimum d'un ID de chaîne unique, d'un type d'élément, d'une LCA, d'une URL et d'une version de 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 celui-ci à l'aide de la commande RepositoryDoc.Builder
.
L'exemple suivant montre comment créer un élément indexable unique.
Un RepositoryDoc
est un type de ApiOperation
qui effectue la fonction 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 de l'indexation vers le temps de diffusion et gère un quota de débit élevé pour les requêtes d'indexation. Le mode asynchrone est recommandé pour l'indexation initiale (remplissage) de l'ensemble du dépôt.
SYNCHRONOUS
- Le mode synchrone a pour effet de réduire la latence d'indexation vers la diffusion et de limiter le quota de débit. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications du dépôt. S'il n'est pas spécifié, le mode de requête par défaut est
SYNCHRONOUS
.
Étapes suivantes
Voici quelques étapes que vous pouvez également suivre :
- (Facultatif) Mettez en œuvre 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 à l'aide d'une classe de modèle
La file d'attente d'indexation Cloud Search contient les ID et les valeurs de hachage facultatives pour chaque élément du dépôt. Un connecteur de balayage de graphe transfère les ID d'éléments vers la file d'attente d'indexation Google Cloud Search, puis les récupère pour les indexer. Google Cloud Search gère les files d'attente et compare leur contenu pour déterminer leur état, par exemple si un élément a été supprimé du dépôt. Pour plus d'informations sur la file d'attente d'indexation Google Search, consultez la page File d'attente d'indexation Google Cloud Search.
Pendant l'index, le contenu des éléments est extrait du dépôt de données et tous les ID d'éléments enfants sont envoyés dans la file d'attente. Le connecteur traite les ID parents et enfants de manière récursive jusqu'à ce que tous les éléments soient traités.
Cette section fait référence aux extraits de code de l'exemple GraphTraversalSample.
Mettre en œuvre 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 mettez en œuvre les méthodes.
L'extrait de code suivant montre comment instancier la ListingConnector
et sa Repository
associée:
En arrière-plan, le SDK appelle la méthode initConfig()
après l'appel de la méthode main()
de votre connecteur Application.build
.
Méthode initConfig()
:
- Il appelle la méthode
Configuation.isInitialized()
pour s'assurer que leConfiguration
n'a pas été initialisé. - 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
La seule fonction de l'objet Repository
est d'effectuer le balayage et l'indexation des éléments du dépôt. 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 la méthode ListingConnector
, 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()
.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()
.Méthode
getDoc()
. Pour ajouter, mettre à jour, modifier ou supprimer des éléments de l'index, ignorez la méthodegetDoc()
.(Facultatif) Méthode
getChanges()
. Si votre dépôt est compatible avec 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) Méthode
close()
. Si vous devez effectuer un nettoyage du dépôt, ignorez 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 type d'objet ApiOperation
. Un objet ApiOperation
effectue une action sous la forme d'un ou plusieurs appels IndexingService.indexItem()
pour effectuer l'indexation réelle de votre dépôt.
Obtenir des paramètres de configuration personnalisés
Dans le cadre de la configuration de votre connecteur, vous devez récupérer tous les paramètres personnalisés de l'objet Configuration
. Cette tâche est généralement effectuée dans la méthode init()
d'une classe Repository
.
La classe Configuration
dispose de 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 suivant, de FullTraversalSample
, montre comment récupérer un seul nombre entier personnalisé à partir d'un objet Configuration
:
Pour obtenir et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration
pour analyser les données en fragments discrets.
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 au niveau d'un élément spécifique en cas d'interruption du processus.
Remplacez ensuite la méthode getDoc()
pour gérer chaque élément de la file d'attente d'indexation Cloud Search.
ID d'élément push et valeurs de hachage
Ignorez getIds()
pour récupérer les ID d'éléments et les valeurs de hachage de contenu associées dans le dépôt. Les paires d'ID et de 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 parent sont généralement transférés en premier, suivis des ID des enfants, jusqu'à ce que l'ensemble de la hiérarchie des éléments ait été traitée.
La méthode getIds()
accepte un point de contrôle représentant le dernier élément à indexer. Le point de contrôle peut être utilisé pour reprendre l'indexation d'un élément spécifique en cas d'interruption du processus. Pour chaque élément du dépôt, procédez comme suit dans la méthode getIds()
:
- Récupérez l'ID de chaque élément et la valeur de hachage associée dans le dépôt.
- Empaquetez chaque paire ID/valeur de hachage dans un élément
PushItems
. - Combinez chaque
PushItems
dans un itérateur renvoyé par la méthodegetIds()
. Notez quegetIds()
renvoie en fait uneCheckpointCloseableIterable
, qui est une itération d'objetsApiOperation
. chaque objet représentant une requête API effectuée sur unRepositoryDoc
, tel que le transfert des éléments vers la file d'attente.
L'extrait de code suivant montre comment obtenir l'ID et la valeur de hachage de chaque élément, et les insérer dans un élément PushItems
. Une requête PushItems
est une requête ApiOperation
visant à envoyer un élément à la file d'attente d'indexation Cloud Search.
L'extrait de code suivant indique comment utiliser
PushItems.Builder
pour empaqueter les ID et les valeurs de hachage en une seule transmissionApiOperation
(Installation de Python groupée).
Les éléments sont placés dans la file d'attente d'indexation Cloud Search en vue d'un traitement ultérieur.
Récupérer et gérer chaque élément
Ignorez getDoc()
pour gérer chaque élément de la file d'attente d'indexation Cloud Search.
Un élément peut être nouveau, modifié ou inchangé, ou ne peut plus exister dans le dépôt source. Récupérez et indexez chaque élément nouveau ou modifié. Supprimez les éléments de l'index 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 de la recherche Google. Pour chaque élément de la file d'attente, procédez comme suit dans la méthode getDoc()
:
Vérifiez si l'ID de l'élément, dans la file d'attente d'indexation Cloud Search, existe dans le dépôt. Si ce n'est pas le cas, supprimez-le de l'index. Si l'élément existe, passez à l'étape suivante.
Index modifié 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 en un seul élément
RepositoryDoc
indexable. - Placez les ID 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, si ce n'est pas le cas, le supprimer.
Définir les autorisations d'un élément
Votre dépôt identifie les utilisateurs ou les groupes ayant accès à un élément à l'aide d'une liste de contrôle d'accès (LCA). Une LCA est une liste d'ID correspondant à des groupes ou des utilisateurs pouvant accéder à l'é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 puissent le voir dans un résultat de recherche. La LCA d'un élément doit être incluse lors de l'indexation d'un élément afin que Google Cloud Search dispose des informations nécessaires pour fournir le niveau d'accès approprié à l'élément.
Le SDK Content Connector propose un grand nombre de méthodes et de classes ACL 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 emploie des concepts tels que l'héritage des LCA, la modélisation de cette LCA peut s'avérer délicate. Pour plus d'informations sur les LCA Google Cloud, consultez la page Listes de contrôle d'accès Google Cloud Search.
Remarque:L'API Cloud Search Indexing accepte les LCA à domaine unique. Il ne prend pas en charge 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 "principals" (getCustomerPrincipal()
) d'être des "lecteurs" de tous les éléments (.setReaders()
) lors d'une recherche ;
Vous devez comprendre les LCA pour modéliser correctement les LCA du dépôt. Par exemple, vous indexez peut-être les fichiers d'un système de fichiers qui utilise un modèle d'héritage selon 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 détaillées dans les 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 un Item
, vous devez disposer au minimum d'un ID de chaîne unique, d'un type d'élément, d'une LCA, d'une URL et d'une version de 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 celui-ci à l'aide de la commande RepositoryDoc.Builder
.
L'exemple suivant montre comment créer un élément indexable unique.
Un RepositoryDoc
est un type de ApiOperation
qui effectue la requête IndexingService.indexItem()
réelle.
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 de l'indexation vers le temps de diffusion et gère un quota de débit élevé pour les requêtes d'indexation. Le mode asynchrone est recommandé pour l'indexation initiale (remplissage) de l'ensemble du dépôt.
SYNCHRONOUS
- Le mode synchrone a pour effet de réduire la latence d'indexation vers la diffusion et de limiter le quota de débit. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications du dépôt. S'il n'est pas spécifié, le mode de requête par défaut est
SYNCHRONOUS
.
placer les ID 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 à des fins de 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) Mettez en œuvre 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 avec 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 à traverser un dépôt et à indexer ses données. Vous devez mettre en œuvre 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 courantes de balayage:
- Stratégie de balayage complet
Une stratégie de balayage complet analyse l'intégralité du dépôt et indexe aveuglement 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 est adaptée aux petits dépôts contenant principalement des données statiques et non hiérarchiques. Vous pouvez également utiliser cette stratégie de balayage lorsque la détection des modifications est difficile ou incompatible avec le dépôt.
- Liste des stratégies de balayage
Une stratégie de balayage de liste permet d'analyser l'ensemble du dépôt, y compris tous les nœuds enfants, en déterminant l'état de chaque élément. Ensuite, le connecteur procède à une deuxième passe et 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 sur un index existant (plutôt que 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 incompatible avec le dépôt, que vous disposez de données non hiérarchiques et que vous travaillez avec des ensembles de données très volumineux.
- Traversée de graphique
Une stratégie de balayage de graphe analyse l'intégralité du nœud parent en déterminant l'état de chaque élément. Ensuite, le connecteur procède à une deuxième passe et seuls les éléments d'index du nœud racine sont nouveaux ou mis à jour depuis la dernière indexation. Enfin, le connecteur transmet les ID enfants, puis indexe les éléments des nœuds enfants qui sont nouveaux ou mis à jour. Le connecteur continue de manière récursive via tous les nœuds enfants jusqu'à ce que tous les éléments aient été traités. Ce parcours est généralement utilisé pour les dépôts hiérarchiques pour lesquels il n'est pas possible de répertorier tous les ID.
Cette stratégie est adaptée si vous devez explorer des données hiérarchiques, telles qu'un annuaire de séries ou des pages Web.
Mettre en œuvre votre stratégie de balayage et indexer des éléments
Chaque élément indexable pour Google Cloud Search est appelé élément dans l'API Cloud Search. Un élément peut être un fichier, un dossier, une ligne dans un fichier CSV ou un enregistrement de base de données.
Une fois le schéma enregistré, vous pouvez remplir l'index comme suit:
(Facultatif) Utilisation de
items.upload
pour importer des fichiers de plus de 100 Kio pour l'indexation. Pour les fichiers plus petits, intégrez le contenu en tant que inlineContent à l'aide deitems.index
.(Facultatif) Utilisation de
media.upload
pour importer des fichiers multimédias pour l'indexation.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 ressemblerait à ceci:{ "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) Utiliser des appels items.get pour vérifier qu'un élément a été indexé.
Pour effectuer un balayage complet, vous devez réindexer régulièrement l'intégralité du dépôt. Pour effectuer un balayage de liste ou de graphe, vous devez mettre en œuvre le code permettant de gérer les modifications du dépôt.
Gérer les modifications du dépôt
Vous pouvez rassembler et indexer régulièrement chaque élément d'un dépôt pour effectuer une indexation complète. Bien qu'il soit efficace pour s'assurer que votre index est à jour, une indexation complète peut s'avérer coûteuse pour les dépôts plus volumineux ou hiérarchiques.
Plutôt que d'utiliser les appels d'index pour indexer un dépôt entier de temps en temps, vous pouvez également utiliser la commandeFile d'attente d'indexation Google Cloud en tant que mécanisme de suivi des modifications et de n'indexer que les éléments modifiés. Vous pouvez utiliser les requêtes items.push pour placer des éléments dans la file d'attente pour les interroger et les mettre à jour ultérieurement. Pour plus d'informations sur la file d'attente d'indexation Google Cloud, reportez-vous à la page File d'attente d'indexation Google Cloud.
Pour en savoir plus sur l'API REST de Cloud Search, consultez l'article API Cloud Search.