Créer un connecteur de contenu

Un connecteur de contenu est un programme logiciel qui permet de balayer les données d'un dépôt d'entreprise et d'insérer une source de données. Google propose les options suivantes pour développer des connecteurs de contenu:

  • Le SDK Content Connector. Cette option est une bonne solution si vous programmez en Java. Le SDK Content Connector est un wrapper pour l'API REST qui 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.

  • API REST ou bibliothèques d'API de bas niveau 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 à l'aide de l'API REST, consultez l'article Créer un connecteur de contenu à l'aide de l'API REST.

Un connecteur de contenu standard exécute les tâches suivantes:

  1. Lit et traite les paramètres de configuration.
  2. Extraction de fragments distincts de données indexables, appelées éléments, à partir du dépôt de contenu tiers
  3. Combine les LCA, les métadonnées et les données de contenu en éléments indexables.
  4. Indexe des éléments dans la source de données Cloud Search.
  5. (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 exécute cette tâche uniquement 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 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 la configuration du connecteur

Chaque connecteur dispose d'un fichier de configuration contenant des paramètres utilisés par le connecteur, tels que l'ID de votre dépôt. Les paramètres sont définis comme des paires clé-valeur telles que api.sourceId=1234567890abcdef.

Le SDK Google Cloud Search contient plusieurs paramètres de configuration fournis par Google qui sont 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 et api.serviceAccountPrivateKeyFile, car ces paramètres identifient l'emplacement de votre dépôt et de la clé privée nécessaires pour y accéder.
  • Pour un connecteur d'identité, vous devez déclarer api.identitySourceId, car ce paramètre identifie l'emplacement de la source d'identité externe. En cas de synchronisation des utilisateurs, déclarez également api.customerId comme ID unique pour le 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 plus d'informations sur les paramètres de configuration fournis par Google, concernant la génération de certains ID et de certaines clés, entre autres, reportez-vous à la page Paramètres de configuration fournis par Google.

Vous pouvez également définir des paramètres propres au dépôt dans votre fichier de configuration.

Transmettre le fichier de configuration au connecteur

Définissez la propriété système config de manière à 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 n'est pas spécifié, 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 est de balayer un dépôt et d'indexer ses données. Vous devez mettre en œuvre une stratégie de balayage basée sur la taille et la mise en page 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 chaque élément à l'aveugle. 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é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.

Stratégie de balayage de liste

Une stratégie de balayage de liste analyse l'ensemble du dépôt, y compris les nœuds enfants, afin de déterminer l'état de chaque élément. Ensuite, le connecteur effectue une seconde passe et n'indexe que les éléments nouveaux ou mis à jour depuis la dernière indexation. Cette stratégie est communément utilisée pour effectuer des mises à jour incrémentielles vers un index existant (au lieu de devoir effectuer un balayage complet à chaque mise à jour de l'index).

Cette stratégie de balayage convient lorsque la détection des modifications est difficile ou non prise en charge par le dépôt, lorsque vous disposez de données non hiérarchiques et que vous travaillez avec des ensembles de données très volumineux.

Traversée de graphe

Une stratégie de balayage de graphe analyse l'ensemble du nœud parent pour 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 qui ont été mis à jour depuis la dernière indexation. Enfin, le connecteur transmet tous les ID enfants, puis indexe les éléments nouveaux ou mis à jour dans les nœuds enfants. Le connecteur continue de manière récursive dans 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 dans lesquels il n'est pas pratique de lister tous les ID.

Cette stratégie convient pour explorer des données hiérarchisées, comme 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 implémenter 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

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 modèle FullTraversalConnector accepte un objet Repository dont vous utiliserez les méthodes. L'extrait de code suivant montre comment mettre en œuvre la méthode main():

FullTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

En arrière-plan, le SDK appelle la méthode initConfig(), après que la méthode main() de votre connecteur a appelé Application.build. La méthode initConfig() accomplit les tâches suivantes:

  1. Appel de la méthode Configuation.isInitialized() pour confirmer que l'objet Configuration n'a pas été initialisé.
  2. Elle initialise un objet Configuration avec les paires clé-valeur fournies par Google. Chaque paire clé/valeur est stockée dans un objet ConfigValue au sein de l'objet Configuration.

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. Ces méthodes dépendent de la stratégie de balayage et du modèle employés. Pour le modèle 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éthode init().

  • La méthode getAllDocs(). Pour balayer et indexer tous les éléments du dépôt de données, remplacez la méthode getAllDocs(). 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éthode getChanges(). Cette méthode est appelée une fois lors de 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 effectuer le nettoyage du dépôt, remplacez la méthode close(). Cette méthode est appelée une fois lors de l'arrêt du connecteur.

Chaque méthode 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 de votre dépôt.

Obtenir des paramètres de configuration personnalisés

Lorsque vous gérez 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 pour obtenir différents types de données à partir d'une configuration. Chaque méthode renvoie un objet ConfigValue. Pour récupérer la valeur réelle, utilisez ensuite la méthode get() de l'objet ConfigValue. L'extrait de code suivant (issu du modèle FullTraversalSample) montre comment récupérer une valeur entière personnalisée à partir d'un objet Configuration:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Pour obtenir et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration, qui permettent d'analyser les données par fragments distincts. L'extrait de code suivant (issu du connecteur du tutoriel) permet d'obtenir la liste des noms de dépôts GitHub grâce à la méthode getMultiValue:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Effectuer un balayage complet

Ignorez 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 donné si le processus est interrompu. Pour chaque élément du dépôt, vous accomplirez les tâches suivantes dans la méthode getAllDocs():

  1. Définissez les autorisations.
  2. Définissez les métadonnées de l'élément que vous indexez.
  3. Combinez les métadonnées et l'élément dans un objet RepositoryDoc indexable.
  4. Empaqueter chaque élément indexable dans un itérateur renvoyé par la méthode getAllDocs() Notez que getAllDocs() renvoie en fait un objet CheckpointCloseableIterable, qui correspond à une itération d'objets ApiOperation, chaque objet représentant une requête API effectuée sur un objet RepositoryDoc (par exemple, une requête d'indexation).

Si l'ensemble d'éléments est trop volumineux pour être traité via un seul appel, insérez un point de contrôle et définissez hasMore(true) pour indiquer que d'autres éléments peuvent être indexés.

Définir les autorisations pour un élément

Votre dépôt utilise 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 pour les groupes ou les 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 autorisés à accéder à un élément puissent le voir dans un résultat de recherche. Cette liste doit être incluse lors de l'indexation de l'élément afin que Google Cloud Search dispose des informations nécessaires pour accorder le niveau d'accès qui convient.

Le SDK Content Connector fournit un ensemble complet de classes et de méthodes LCA permettant de modéliser les LCA de la plupart des dépôts. Vous devez analyser la LCA de chaque élément du dépôt et créer une LCA correspondant à 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 de la LCA, la modélisation de cette LCA peut s'avérer délicate. Pour en savoir plus sur les LCA de Google Cloud Search, reportez-vous à la section LCA de Google Cloud Search.

Remarque:L'API Cloud Search Indexing est compatible avec les LCA à domaine unique. mais pas 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, tiré 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.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Vous devez comprendre les LCA afin de les modéliser correctement pour le dépôt. Par exemple, vous pouvez indexer des fichiers dans un système de fichiers qui utilise un 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 détaillées dans 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 un objet Item, vous avez besoin d'au moins un ID de chaîne unique, un type d'élément, une LCA, une URL et une version. L'extrait de code suivant montre comment créer un Item à l'aide de la classe d'assistance IndexingItemBuilder.

FullTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Créer l'élément indexable

Après avoir défini les métadonnées de l'élément, vous pouvez créer l'élément indexable avec la classe RepositoryDoc.Builder. L'exemple suivant montre comment créer un seul élément indexable.

FullTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

Un RepositoryDoc est un type d'objet ApiOperation qui exécute la requête IndexingService.indexItem().

Vous pouvez également utiliser la méthode setRequestMode() de la classe RepositoryDoc.Builder pour identifier ASYNCHRONOUS ou SYNCHRONOUS comme suit la requête d'indexation:

ASYNCHRONOUS
Le mode asynchrone augmente la latence entre l'indexation et la diffusion des éléments, mais autorise un débit élevé pour les requêtes d'indexation. Il est recommandé pour l'indexation initiale (le remplissage) du dépôt complet.
SYNCHRONOUS
Le mode synchrone diminue la latence entre l'indexation et la diffusion des éléments, mais autorise un débit moindre. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications apportées au dépôt. Si aucune valeur n'est spécifiée, le mode de requête par défaut est 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 construire et renvoyer un itérateur. L'extrait de code suivant montre comment construire et renvoyer un itérateur.

FullTraversalSample.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

Le SDK exécute chaque appel d'indexation figurant dans l'itérateur.

Étapes suivantes

Voici quelques étapes que vous pouvez également suivre :

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 de chaque élément du dépôt ainsi que la valeur de hachage associée (le cas échéant). Un connecteur de balayage de liste place les ID d'élément 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 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, reportez-vous à la section 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 utiliserez les méthodes. L'extrait de code suivant montre comment instancier ListingConnector et le Repository associé:

ListTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

En arrière-plan, le SDK appelle la méthode initConfig(), après que la méthode main() de votre connecteur a appelé Application.build. La méthode initConfig():

  1. Appel de la méthode Configuation.isInitialized() pour confirmer que l'objet Configuration n'a pas été initialisé.
  2. Elle initialise un objet Configuration avec les paires clé-valeur fournies par Google. Chaque paire clé/valeur est stockée dans un objet ConfigValue au sein de l'objet Configuration.

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. Ces méthodes dépendent de la stratégie de balayage et du modèle employés. Pour le modèle 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éthode init().

  • La méthode getIds(). Pour récupérer les ID et les valeurs de hachage de l'ensemble des enregistrements du dépôt, remplacez la méthode getIds().

  • La méthode getDoc(). Pour ajouter, mettre à jour, modifier ou supprimer des éléments de l'index, remplacez la méthode getDoc().

  • (Facultatif) La méthode getChanges(). Si votre dépôt accepte la détection des modifications, remplacez la méthode getChanges(). Cette méthode est appelée une fois lors de 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 effectuer le nettoyage du dépôt, remplacez la méthode close(). Cette méthode est appelée une fois lors de l'arrêt du connecteur.

Chaque méthode 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 de votre dépôt.

Obtenir des paramètres de configuration personnalisés

Lorsque vous gérez 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 pour obtenir différents types de données à partir d'une configuration. Chaque méthode renvoie un objet ConfigValue. Pour récupérer la valeur réelle, utilisez ensuite la méthode get() de l'objet ConfigValue. L'extrait de code suivant (issu du modèle FullTraversalSample) montre comment récupérer une valeur entière personnalisée à partir d'un objet Configuration:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Pour obtenir et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration, qui permettent d'analyser les données par fragments distincts. L'extrait de code suivant (issu du connecteur du tutoriel) permet d'obtenir la liste des noms de dépôts GitHub grâce à la méthode getMultiValue:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Effectuer un balayage de liste

Remplacez la méthode getIds() afin de récupérer les ID et les valeurs de hachage de l'ensemble des 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 donné si le processus est interrompu.

Remplacez ensuite la méthode getDoc() pour gérer chaque élément de la file d'attente d'indexation Cloud Search.

Transmettre les ID et 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 de transmission et placées dans la file d'attente d'indexation Cloud Search. Les ID des éléments racines ou parents sont généralement transmis en premier, suivis des ID des éléments enfants, jusqu'à ce que l'ensemble de la hiérarchie des éléments ait été traité.

La méthode getIds() accepte un point de contrôle représentant le dernier élément à indexer. Le point de contrôle peut servir à reprendre l'indexation à partir d'un élément donné 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 et la valeur de hachage associée (le cas échéant) pour chaque élément du dépôt.
  • Empaquetez chaque paire ID/valeur de hachage dans un objet PushItems.
  • Combinez chaque objet PushItems dans un itérateur renvoyé par la méthode getIds(). Notez que getIds() renvoie en réalité un objet CheckpointCloseableIterable, qui correspond à une itération d'objets ApiOperation, chaque objet représentant une requête API effectuée sur un objet RepositoryDoc tel que la mise en file d'attente des éléments.

L'extrait de code suivant montre comment récupérer l'ID et la valeur de hachage de chaque élément, puis insérer ces informations dans un objet PushItems. Un objet PushItems correspond à une requête ApiOperation visant à placer un élément dans la file d'attente d'indexation Cloud Search.

ListTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

L'extrait de code suivant montre comment utiliser la classe PushItems.Builder pour empaqueter les ID et les valeurs de hachage dans un seul objet ApiOperation de transmission.

ListTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

Les éléments sont placés dans la file d'attente d'indexation Cloud Search pour traitement.

Récupérer et traiter chaque élément

Remplacez la méthode getDoc() afin de traiter chaque élément de la file d'attente d'indexation Cloud Search. Un élément peut être nouveau, modifié, inchangé ou n'existe plus dans le dépôt source. Récupérez et indexez chaque élément nouveau ou modifié. Supprimez de l'index ceux 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, vous accomplirez les tâches suivantes dans la méthode getDoc():

  1. Vérifiez si l'élément figure dans le dépôt, d'après son ID dans la file d'attente d'indexation Cloud Search. Si ce n'est pas le cas, supprimez l'élément de l'index.

  2. Interrogez l'index pour connaître l'état de l'élément. Si celui-ci n'a pas changé (ACCEPTED), ne faites rien.

  3. Index des éléments modifiés ou nouveaux:

    1. Définissez les autorisations.
    2. Définissez les métadonnées de l'élément que vous indexez.
    3. Combinez les métadonnées et l'élément dans un objet RepositoryDoc indexable.
    4. Renvoyez RepositoryDoc.

Remarque:Le modèle ListingConnector ne permet pas de renvoyer une valeur null sur la méthode getDoc(). Le renvoi d'une valeur null génère une erreur 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.

ListTraversalSample.java
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

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 comment traiter un élément non modifié.

ListTraversalSample.java
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

Pour déterminer si l'élément est inchangé, vérifiez son état ainsi que les autres métadonnées susceptibles d'indiquer un changement. Dans l'exemple, le hachage des métadonnées permet de déterminer si l'élément a été modifié.

ListTraversalSample.java
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

Définir les autorisations pour un élément

Votre dépôt utilise 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 pour les groupes ou les 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 autorisés à accéder à un élément puissent le voir dans un résultat de recherche. Cette liste doit être incluse lors de l'indexation de l'élément afin que Google Cloud Search dispose des informations nécessaires pour accorder le niveau d'accès qui convient.

Le SDK Content Connector fournit un ensemble complet de classes et de méthodes LCA permettant de modéliser les LCA de la plupart des dépôts. Vous devez analyser la LCA de chaque élément du dépôt et créer une LCA correspondant à 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 de la LCA, la modélisation de cette LCA peut s'avérer délicate. Pour en savoir plus sur les LCA de Google Cloud Search, reportez-vous à la section LCA de Google Cloud Search.

Remarque:L'API Cloud Search Indexing est compatible avec les LCA à domaine unique. mais pas 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, tiré 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.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Vous devez comprendre les LCA afin de les modéliser correctement pour le dépôt. Par exemple, vous pouvez indexer des fichiers dans un système de fichiers qui utilise un 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 détaillées dans 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 un objet Item, vous avez besoin d'au moins un ID de chaîne unique, un type d'élément, une LCA, une URL et une version. L'extrait de code suivant montre comment créer un Item à l'aide de la classe d'assistance IndexingItemBuilder.

ListTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

Créer un élément indexable

Après avoir défini les métadonnées de l'élément, vous pouvez créer l'élément indexable avec la classe RepositoryDoc.Builder. L'exemple suivant montre comment créer un seul élément indexable.

ListTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

Un RepositoryDoc est un type d'objet ApiOperation qui exécute la requête IndexingService.indexItem().

Vous pouvez également utiliser la méthode setRequestMode() de la classe RepositoryDoc.Builder pour identifier ASYNCHRONOUS ou SYNCHRONOUS comme suit la requête d'indexation:

ASYNCHRONOUS
Le mode asynchrone augmente la latence entre l'indexation et la diffusion des éléments, mais autorise un débit élevé pour les requêtes d'indexation. Il est recommandé pour l'indexation initiale (le remplissage) du dépôt complet.
SYNCHRONOUS
Le mode synchrone diminue la latence entre l'indexation et la diffusion des éléments, mais autorise un débit moindre. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications apportées au dépôt. Si aucune valeur n'est spécifiée, le mode de requête par défaut est SYNCHRONOUS.

Étapes suivantes

Voici quelques étapes que vous pouvez également suivre :

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 de chaque élément du dépôt ainsi que la valeur de hachage associée (le cas échéant). Un connecteur de balayage de graphe place les ID d'élément dans la file d'attente d'indexation de 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 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, reportez-vous à la section File d'attente d'indexation de Google Cloud Search.

Pendant l'indexation, le contenu des éléments est récupéré dans le dépôt de données et les ID des éléments enfants sont placés dans la file d'attente. Le connecteur procède au traitement récursif des ID parent 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 modèle ListingConnector accepte un objet Repository dont vous utiliserez les méthodes.

L'extrait de code suivant montre comment instancier ListingConnector et le Repository associé:

GraphTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

En arrière-plan, le SDK appelle la méthode initConfig(), après que la méthode main() de votre connecteur a appelé Application.build. La méthode initConfig():

  1. Appel de la méthode Configuation.isInitialized() pour confirmer que l'objet Configuration n'a pas été initialisé.
  2. Elle initialise un objet Configuration avec les paires clé-valeur fournies par Google. Chaque paire clé/valeur est stockée dans un objet ConfigValue au sein de l'objet Configuration.

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. Ces méthodes dépendent de la stratégie de balayage et du modèle employés. Pour le modèle ListingConnector, par exemple, vous remplacerez les méthodes suivantes:

  • La méthode init(). Pour configurer et initialiser un dépôt de données, remplacez la méthode init().

  • La méthode getIds(). Pour récupérer les ID et les valeurs de hachage de l'ensemble des enregistrements du dépôt, remplacez la méthode getIds().

  • La méthode getDoc(). Pour ajouter, mettre à jour, modifier ou supprimer des éléments de l'index, remplacez la méthode getDoc().

  • (Facultatif) La méthode getChanges(). Si votre dépôt accepte la détection des modifications, remplacez la méthode getChanges(). Cette méthode est appelée une fois lors de 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 effectuer le nettoyage du dépôt, remplacez la méthode close(). Cette méthode est appelée une fois lors de l'arrêt du connecteur.

Chaque méthode 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 de votre dépôt.

Obtenir des paramètres de configuration personnalisés

Lorsque vous gérez 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 pour obtenir différents types de données à partir d'une configuration. Chaque méthode renvoie un objet ConfigValue. Pour récupérer la valeur réelle, utilisez ensuite la méthode get() de l'objet ConfigValue. L'extrait de code suivant (issu du modèle FullTraversalSample) montre comment récupérer une valeur entière personnalisée à partir d'un objet Configuration:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Pour obtenir et analyser un paramètre contenant plusieurs valeurs, utilisez l'un des analyseurs de type de la classe Configuration, qui permettent d'analyser les données par fragments distincts. L'extrait de code suivant (issu du connecteur du tutoriel) permet d'obtenir la liste des noms de dépôts GitHub grâce à la méthode getMultiValue:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Effectuer un balayage de graphe

Remplacez la méthode getIds() afin de récupérer les ID et les valeurs de hachage de l'ensemble des 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 donné si le processus est interrompu.

Remplacez ensuite la méthode getDoc() pour gérer chaque élément de la file d'attente d'indexation Cloud Search.

Transmettre les ID et 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 de transmission et placées dans la file d'attente d'indexation Cloud Search. Les ID des éléments racines ou parents sont généralement transmis en premier, suivis des ID des éléments enfants, jusqu'à ce que l'ensemble de la hiérarchie des éléments ait été traité.

La méthode getIds() accepte un point de contrôle représentant le dernier élément à indexer. Le point de contrôle peut servir à reprendre l'indexation à partir d'un élément donné 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 et la valeur de hachage associée (le cas échéant) pour chaque élément du dépôt.
  • Empaquetez chaque paire ID/valeur de hachage dans un objet PushItems.
  • Combinez chaque objet PushItems dans un itérateur renvoyé par la méthode getIds(). Notez que getIds() renvoie en réalité un objet CheckpointCloseableIterable, qui correspond à une itération d'objets ApiOperation, chaque objet représentant une requête API effectuée sur un objet RepositoryDoc tel que la mise en file d'attente des éléments.

L'extrait de code suivant montre comment récupérer l'ID et la valeur de hachage de chaque élément, puis insérer ces informations dans un objet PushItems. Un objet PushItems correspond à une requête ApiOperation visant à placer un élément dans la file d'attente d'indexation Cloud Search.

GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

L'extrait de code suivant montre comment utiliser la classe PushItems.Builder pour empaqueter les ID et les valeurs de hachage dans un seul objet ApiOperation de transmission.

GraphTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

Les éléments sont placés dans la file d'attente d'indexation Cloud Search pour traitement.

Récupérer et traiter chaque élément

Remplacez la méthode getDoc() afin de traiter chaque élément de la file d'attente d'indexation Cloud Search. Un élément peut être nouveau, modifié, inchangé ou n'existe plus dans le dépôt source. Récupérez et indexez chaque élément nouveau ou modifié. Supprimez de l'index ceux 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, vous accomplirez les tâches suivantes dans la méthode getDoc():

  1. Vérifiez si l'élément figure dans le dépôt, d'après son ID 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.

  2. Index des éléments modifiés ou nouveaux:

    1. Définissez les autorisations.
    2. Définissez les métadonnées de l'élément que vous indexez.
    3. Combinez les métadonnées et l'élément dans un objet RepositoryDoc indexable.
    4. Placez les ID enfants dans la file d'attente d'indexation Cloud Search afin qu'ils soient traités.
    5. 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 le supprimer.

GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

Définir les autorisations pour un élément

Votre dépôt utilise 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 pour les groupes ou les 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 autorisés à accéder à un élément puissent le voir dans un résultat de recherche. Cette liste doit être incluse lors de l'indexation de l'élément afin que Google Cloud Search dispose des informations nécessaires pour accorder le niveau d'accès qui convient.

Le SDK Content Connector fournit un ensemble complet de classes et de méthodes LCA permettant de modéliser les LCA de la plupart des dépôts. Vous devez analyser la LCA de chaque élément du dépôt et créer une LCA correspondant à 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 de la LCA, la modélisation de cette LCA peut s'avérer délicate. Pour en savoir plus sur les LCA de Google Cloud Search, reportez-vous à la section LCA de Google Cloud Search.

Remarque:L'API Cloud Search Indexing est compatible avec les LCA à domaine unique. mais pas 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, tiré 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.

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Vous devez comprendre les LCA afin de les modéliser correctement pour le dépôt. Par exemple, vous pouvez indexer des fichiers dans un système de fichiers qui utilise un 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 détaillées dans 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 un objet Item, vous avez besoin d'au moins un ID de chaîne unique, un type d'élément, une LCA, une URL et une version. L'extrait de code suivant montre comment créer un Item à l'aide de la classe d'assistance IndexingItemBuilder.

GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Créer l'élément indexable

Après avoir défini les métadonnées de l'élément, vous pouvez créer l'élément indexable avec la classe RepositoryDoc.Builder. L'exemple suivant montre comment créer un seul élément indexable.

GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

Un RepositoryDoc est un type d'objet ApiOperation qui exécute la requête IndexingService.indexItem().

Vous pouvez également utiliser la méthode setRequestMode() de la classe RepositoryDoc.Builder pour identifier ASYNCHRONOUS ou SYNCHRONOUS comme suit la requête d'indexation:

ASYNCHRONOUS
Le mode asynchrone augmente la latence entre l'indexation et la diffusion des éléments, mais autorise un débit élevé pour les requêtes d'indexation. Il est recommandé pour l'indexation initiale (le remplissage) du dépôt complet.
SYNCHRONOUS
Le mode synchrone diminue la latence entre l'indexation et la diffusion des éléments, mais autorise un débit moindre. Le mode synchrone est recommandé pour l'indexation des mises à jour et des modifications apportées au dépôt. Si aucune valeur n'est spécifiée, le mode de requête par défaut est 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 le traitement. Ces ID sont traités après l'indexation de l'élément parent.

GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

Étapes suivantes

Voici quelques étapes que vous pouvez également suivre :

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 est de balayer un dépôt et d'indexer ses données. Vous devez mettre en œuvre une stratégie de balayage basée sur la taille et la mise en page 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 analyse l'intégralité du dépôt et indexe chaque élément à l'aveugle. 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é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.

Stratégie de balayage de liste

Une stratégie de balayage de liste analyse l'ensemble du dépôt, y compris les nœuds enfants, afin de déterminer l'état de chaque élément. Ensuite, le connecteur effectue une seconde passe et n'indexe que les éléments nouveaux ou mis à jour depuis la dernière indexation. Cette stratégie est communément utilisée pour effectuer des mises à jour incrémentielles vers un index existant (au lieu de devoir effectuer un balayage complet à chaque mise à jour de l'index).

Cette stratégie de balayage convient lorsque la détection des modifications est difficile ou non prise en charge par le dépôt, lorsque vous disposez de données non hiérarchiques et que vous travaillez avec des ensembles de données très volumineux.

Traversée de graphe

Une stratégie de balayage de graphe analyse l'ensemble du nœud parent pour 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 qui ont été mis à jour depuis la dernière indexation. Enfin, le connecteur transmet tous les ID enfants, puis indexe les éléments nouveaux ou mis à jour dans les nœuds enfants. Le connecteur continue de manière récursive dans 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 dans lesquels il n'est pas pratique de lister tous les ID.

Cette stratégie convient pour explorer des données hiérarchiques, comme 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 dans un fichier CSV ou un enregistrement de base de données.

Une fois le schéma enregistré, vous pouvez remplir l'index de différentes manières:

  1. (Facultatif) Utilisation de items.upload pour importer des fichiers de plus de 100 Kio en vue de l'indexation. Pour les fichiers plus petits, intégrez le contenu en tant que inlineContent avec items.index.

  2. (Facultatif) Utilisation de media.upload pour importer des fichiers multimédias à indexer.

  3. 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ésentera 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"
}

  4. (Facultatif) Utilisation 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, du code doit être ajouté pour pouvoir 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 de s'assurer que votre index est à jour, l'indexation complète peut s'avérer coûteuse lorsque vous gérez des dépôts plus volumineux ou hiérarchiques.

Au lieu de multiplier les appels d'index pour indexer un dépôt entier, vous pouvez vous servir de la file d'attente d'indexation Google Cloud Search. Cette file d'attente permet d'effectuer le suivi des modifications des éléments et d'indexer uniquement ceux qui ont changé. Vous pouvez utiliser les requêtes items.push pour placer des éléments dans la file d'attente. Vous pourrez interroger et mettre à jour ces éléments plus tard. Pour en savoir plus sur la file d'attente d'indexation Google Cloud, reportez-vous à la section File d'attente d'indexation de Google Cloud.

Pour en savoir plus sur l'API Google Cloud Search, reportez-vous à la section API Cloud Search.