Files d'attente d'indexation Google Cloud Search

Le SDK Connector et l'API Google Cloud Search permettent de créer des files d'attente d'indexation Cloud Search pour effectuer les tâches suivantes:

• Conservez l'état par document (état, valeurs de hachage, etc.), ce qui peut être utilisé pour synchroniser votre index avec votre dépôt.

• Conservez une liste des éléments à indexer selon le processus de balayage.

• Hiérarchisez les éléments de la file d'attente en fonction de leur état.

• Conservez des informations d'état supplémentaires pour une intégration efficace, telles que des points de contrôle, des jetons de modification, etc.

Une file d'attente est un libellé attribué à un élément indexé, par exemple "default" pour la file d'attente par défaut ou "B" pour la file d'attente B.

État et priorité

La priorité d'un document dans une file d'attente est basée sur son code ItemStatus. Voici les codes ItemStatus possibles par ordre de priorité (traité de la première à la dernière):

• ERROR : l'élément a rencontré une erreur asynchrone lors du processus d'indexation et doit être réindexé.

• MODIFIED : élément précédemment indexé, mais qui a été modifié dans le dépôt depuis la dernière indexation.

• NEW_ITEM : élément non indexé.

• ACCEPTED : document précédemment indexé et qui n'a pas été modifié dans le dépôt depuis la dernière indexation.

Lorsque deux éléments d'une file d'attente ont le même état, une priorité plus élevée est accordée à ceux qui se trouvent dans la file d'attente depuis le plus longtemps.

Présentation de l'utilisation des files d'attente d'indexation pour indexer un élément nouveau ou modifié

La figure 1 montre les étapes d'indexation d'un élément nouveau ou modifié à l'aide d'une file d'attente d'indexation. Ces étapes présentent les appels d'API REST. Pour les appels SDK équivalents, consultez la section Opérations de file d'attente (SDK Connector).

Figure 1. Étapes d'indexation pour l'ajout ou la mise à jour d'un élément

1. Le connecteur de contenu utilise items.push pour placer des éléments (métadonnées et hachage) dans une file d'attente d'indexation afin d'établir leur état (MODIFIED, NEW_ITEM, DELETED). Plus précisément:

   • Lors du transfert, le connecteur inclut explicitement une commande push type ou contentHash.
   • Si le connecteur n'inclut pas l'élément type, Cloud Search utilise automatiquement cet élément contentHash pour déterminer l'état de l'élément.
   • Si l'élément est inconnu, son état est défini sur NEW_ITEM.
   • Si l'élément existe et que les valeurs de hachage correspondent, l'état est conservé sur ACCEPTED.
   • Si l'élément existe et que les valeurs de hachage diffèrent, l'état devient MODIFIED.

   Pour en savoir plus sur la manière dont l'état d'un élément est établi, reportez-vous à l'exemple de code Traverser les dépôts GitHub du tutoriel de mise en route de Cloud Search.

   En général, la transmission est associée à des processus de balayage de contenu et/ou de détection des modifications dans le connecteur.

2. Le connecteur de contenu interroge la file d'attente et détermine les éléments à indexer à l'aide de items.poll. Cloud Search indique au connecteur les éléments qui nécessitent le plus d'indexation, en les triant d'abord par code d'état, puis par temps de file d'attente.

3. Le connecteur récupère ces éléments du dépôt et crée des requêtes d'API d'index.

4. Le connecteur utilise items.index pour indexer les éléments. L'élément ne passe à l'état ACCEPTED qu'une fois le traitement de l'élément terminé par Cloud Search.

Un connecteur peut également supprimer un élément s'il n'existe plus dans le dépôt, ou transférer à nouveau un élément s'il n'est pas modifié ou en cas d'erreur du dépôt source. Pour en savoir plus sur la suppression d'éléments, consultez la section suivante.

Remarque :Certaines stratégies de balayage, telles que le balayage complet, utilisent plusieurs files d'attente d'indexation. Pour obtenir un exemple d'utilisation de deux files d'attente, reportez-vous à la section suivante.

Présentation de l'utilisation de files d'attente d'indexation pour supprimer un élément

La stratégie de balayage complet utilise un processus à deux files d'attente pour indexer les éléments et détecter les suppressions. La figure 2 montre les étapes de suppression d'un élément à l'aide de deux files d'attente d'indexation. Plus précisément, la figure 2 illustre le deuxième balayage effectué à l'aide d'une stratégie de balayage complet. Ces étapes utilisent des appels d'API REST. Pour obtenir des appels au SDK équivalents, consultez la section Opérations de file d'attente (SDK de connecteur).

Figure 2 : Supprimer des éléments

Remarque :Dans la liste d'étapes suivante, les étapes 1 à 4 ne sont pas représentées dans la figure 2, car elles sont identiques aux étapes 1 à 4 du schéma précédent et ne sont pas concernées par cette section. L'étape 5 n'est pas affichée, car l'appel de deleteQueueItems sur une file d'attente vide n'entre pas dans le champ d'application de cette section. Ce schéma se concentre sur le deuxième balayage.

1. Lors du balayage initial, le connecteur de contenu utilise items.push pour placer des éléments (métadonnées et hachage) dans une file d'attente d'indexation, dans laquelle la "file d'attente A" est définie sur NEW_ITEM, car elle n'existe pas dans la file d'attente. Chaque élément se voit attribuer l'étiquette "A" pour "file d'attente A". Le contenu est indexé dans Cloud Search.

   Remarque :Le connecteur peut attribuer un libellé de file d'attente à un élément lors d'une opération item.push ou item.index à l'aide du champ queue de l'élément. Ce libellé peut être modifié chaque fois que l'élément est renvoyé ou réindexé.

2. Le connecteur de contenu utilise items.poll pour interroger la file d'attente A afin de déterminer les éléments à indexer. Cloud Search indique au connecteur les éléments qui nécessitent le plus d'indexation, en les triant d'abord par code d'état, puis par temps de file d'attente.

3. Le connecteur récupère ces éléments du dépôt et crée des requêtes d'API d'index.

4. Le connecteur utilise items.index pour indexer les éléments. L'élément ne passe à l'état ACCEPTED qu'une fois le traitement de l'élément terminé par Cloud Search.

5. La méthode deleteQueueItems est appelée dans la "file d'attente B". Mais aucun élément n'a été placé dans la file d'attente B. Rien ne peut donc être supprimé.

6. Lors du deuxième balayage complet, le connecteur de contenu utilise items.push pour insérer des éléments (métadonnées et hachage) dans la file d'attente B:

   • Lors du transfert, le connecteur inclut explicitement une commande push type ou contentHash.
   • Si le connecteur n'inclut pas l'élément type, Cloud Search utilise automatiquement cet élément contentHash pour déterminer l'état de l'élément.
   • Si l'élément est inconnu, son état est défini sur NEW_ITEM et le libellé de la file d'attente est remplacé par "B".
   • Si l'élément existe et que les valeurs de hachage correspondent, l'état est conservé sur ACCEPTED et le libellé de la file d'attente est remplacé par "B".
   • Si l'élément existe et que les hachages diffèrent, l'état devient MODIFIED et le libellé de la file d'attente passe à "B".

7. Le connecteur de contenu interroge la file d'attente et détermine les éléments à indexer à l'aide de items.poll. Cloud Search indique au connecteur les éléments qui nécessitent le plus d'indexation, en les triant d'abord par code d'état, puis par temps de file d'attente.

8. Le connecteur récupère ces éléments du dépôt et crée des requêtes d'API d'index.

9. Le connecteur utilise items.index pour indexer les éléments. L'élément ne passe à l'état ACCEPTED qu'une fois le traitement de l'élément terminé par Cloud Search.

10. Enfin, deleteQueueItems est appelé dans la file d'attente A pour supprimer tous les éléments CCloud Search précédemment indexés qui possèdent toujours un libellé de file d'attente "A".

11. Lors des balayages complets suivants, la file d'attente utilisée pour l'indexation et celle utilisée pour la suppression sont échangées.

Opérations de file d'attente (SDK Connector)

Le SDK Content Connector fournit des opérations permettant d'ajouter et d'extraire des éléments d'une file d'attente.

Pour empaqueter un élément et le placer dans une file d'attente, utilisez la classe de compilateur pushItems.

Aucune action de votre part n'est requise pour extraire les éléments d'une file d'attente à traiter. À la place, le SDK extrait automatiquement les éléments de la file d'attente, par ordre de priorité, à l'aide de la méthode getDoc de la classe Repository.

Opérations de file d'attente (API REST)

L'API REST fournit les deux méthodes suivantes pour placer et extraire des éléments d'une file d'attente:

• Pour ajouter un élément à une file d'attente, utilisez Items.push.
• Pour interroger des éléments de la file d'attente, utilisez Items.poll.

Vous pouvez également utiliser Items.index pour ajouter des éléments à la file d'attente pendant l'indexation. Les éléments ajoutés à la file d'attente lors de l'indexation ne nécessitent pas de type et se voient automatiquement attribuer l'état ACCEPTED.

Items.push

La méthode Items.push ajoute des ID à la file d'attente. Cette méthode peut être appelée avec une valeur type spécifique qui détermine le résultat de l'opération d'envoi. Pour obtenir la liste des valeurs type, consultez le champ item.type dans la méthode Items.push.

Le transfert d'un nouvel ID entraîne l'ajout d'une nouvelle entrée avec un code NEW_ITEM ItemStatus.

La charge utile facultative est toujours stockée, traitée comme une valeur opaque et renvoyée par Items.poll.

Lorsqu'un élément est interrogé, il est réservé, ce qui signifie qu'il ne peut pas être renvoyé par un autre appel à Items.poll. L'utilisation de Items.push avec type comme NOT_MODIFIED, REPOSITORY_ERROR ou REQUEUE permet d'annuler la réservation des entrées d'interrogation. Pour en savoir plus sur les entrées réservées et non réservées, reportez-vous à la section Items.poll.

Items.push avec hachage

L'API Google Cloud Search permet de spécifier des valeurs de hachage des métadonnées et du contenu dans les requêtes Items.index. Au lieu de spécifier type, vous pouvez spécifier les valeurs de hachage des métadonnées et/ou du contenu avec une requête push. La file d'attente d'indexation Cloud Search compare les valeurs de hachage fournies aux valeurs stockées disponibles avec l'élément de la source de données. En cas d'incohérence, cette entrée est marquée comme MODIFIED. Si un élément correspondant n'existe pas dans l'index, l'état est NEW_ITEM.

Remarque :Les valeurs de hachage fournies avec les requêtes Items.push ne sont pas enregistrées avec l'élément. Ces éléments ne servent qu'à déterminer si l'élément a été modifié.

Items.poll

La méthode Items.poll récupère les entrées ayant la priorité la plus élevée dans la file d'attente. Les valeurs d'état demandées et renvoyées indiquent l'état de la ou des files d'attente prioritaires demandées ou l'état des ID renvoyés.

Par défaut, les entrées de n'importe quelle section de la file d'attente peuvent être renvoyées, en fonction de la priorité. Chaque entrée renvoyée est réservée et n'est pas renvoyée par d'autres appels à Items.poll tant que l'un des cas suivants ne se produit pas:

• La réservation expire.
• L'entrée est de nouveau mise en file d'attente par Items.index.
• Items.push est appelé avec une valeur type de NOT_MODIFIED, REPOSITORY_ERROR ou REQUEUE.