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:

  • Déterminer l'état d'indexation de chaque document (état, valeurs de hachage, etc.) ce qui permet de synchroniser l'index avec votre dépôt

  • Établir la liste des éléments à indexer selon l'analyse effectuée durant le processus de balayage

  • Établir l'ordre de priorité des éléments figurant dans la file d'attente en fonction de leur état d'indexation

  • Déterminer d'autres informations d'état favorisant une intégration efficace, telles que les points de contrôle, les jetons de modification, etc.

Une file d'attente est un libellé attribué à un élément indexé, tel que "par défaut" 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 fonction de son code ItemStatus. Voici les codes ItemStatus possibles par ordre de priorité (de la plus forte à la plus faible):

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

  • MODIFIED : élément déjà 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, la priorité est donnée à celui qui figure 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'indexation. Ces étapes montrent les appels d'API REST. Pour connaître les appels de SDK équivalents, consultez la section Opérations de file d'attente (SDK Connector).

Présentation de l'indexation Google Cloud Search
Figure 1. Procédure d'indexation pour ajouter ou modifier un élément

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

    • Lors de la diffusion, le connecteur inclut explicitement une diffusion type ou contentHash.
    • Si le connecteur n'inclut pas type, Cloud Search utilise automatiquement contentHash pour déterminer l'état de l'élément.
    • Si l'article est inconnu, son état est défini sur NEW_ITEM.
    • Si l'élément existe et que les valeurs de hachage correspondent, l'état reste ACCEPTED.
    • Si l'élément existe et que les hachages sont différents, l'état devient MODIFIED.

    Pour en savoir plus sur l'état des éléments, consultez l'exemple de code Parcourir les dépôts GitHub dans le tutoriel de démarrage de Cloud Search.

    En règle générale, le transfert est associé aux processus de parcours du contenu et/ou de détection des modifications dans le connecteur.

  2. Le connecteur de contenu utilise items.poll pour interroger la file d'attente afin de déterminer les éléments à indexer. Cloud Search indique au connecteur les éléments qui ont le plus besoin d'être indexés, triés d'abord par code d'état, puis par temps d'attente dans la file d'attente.

  3. Le connecteur récupère ces éléments à partir 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 n'entre dans l'état ACCEPTED qu'une fois que Cloud Search a terminé de le traiter.

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

Présentation de l'utilisation des 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'indexation. Plus précisément, la figure 2 montre la deuxième traversée effectuée à l'aide d'une stratégie de traversée complète. Ces étapes utilisent les appels d'API REST. Pour les appels de SDK équivalents, consultez la section Opérations de file d'attente (SDK Connector).

Présentation de l'indexation Google Cloud Search
Figure 2. Supprimer des éléments

  1. Lors du premier balayage, le connecteur de contenu utilise items.push pour insérer des éléments (métadonnées et hachage) dans une file d'indexation, "file A" en tant que NEW_ITEM, car il n'existe pas dans la file. Chaque élément est associé au libellé "A" pour "file d'attente A". Le contenu est indexé dans Cloud Search.

  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 ont le plus besoin d'être indexés, triés d'abord par code d'état, puis par temps d'attente dans la file d'attente.

  3. Le connecteur récupère ces éléments à partir 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 n'entre dans l'état ACCEPTED qu'une fois que Cloud Search a terminé de le traiter.

  5. La méthode deleteQueueItems est appelée sur "queue B". Toutefois, aucun élément n'a été transféré vers la file d'attente B. Rien ne peut donc être supprimé.

  6. Lors de la deuxième traversée complète, 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 de la transmission, le connecteur inclut explicitement une transmission type ou contentHash.
    • Si le connecteur n'inclut pas type, Cloud Search utilise automatiquement 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 reste ACCEPTED et le libellé de la file d'attente est remplacé par "B."
    • Si l'élément existe et que les hachages sont différents, l'état devient MODIFIED et le libellé de la file d'attente est remplacé par "B."

  7. Le connecteur de contenu utilise items.poll pour interroger la file d'attente afin de déterminer les éléments à indexer. Cloud Search indique au connecteur les éléments qui ont le plus besoin d'être indexés, triés d'abord par code d'état, puis par temps d'attente dans la file d'attente.

  8. Le connecteur récupère ces éléments à partir 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 n'entre dans l'état ACCEPTED qu'une fois que Cloud Search a terminé de le traiter.

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

  11. Lors des traversées complètes ultérieures, la file d'attente utilisée pour l'indexation et la file d'attente 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 des éléments à une file d'attente ou d'en retirer.

Pour empaqueter et ajouter un élément à une file d'attente, utilisez la classe de générateur pushItems.

Vous n'avez rien de particulier à faire pour retirer des éléments d'une file d'attente à traiter. Au lieu de cela, le SDK extrait automatiquement des é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 permettant d'ajouter et de retirer des éléments dans une file d'attente:

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

Vous pouvez également ajouter des éléments à la file d'attente pendant l'indexation avec Items.index. Les éléments insérés dans la file d'attente lors de l'indexation ne nécessitent pas de type et sont automatiquement attribués à l'état ACCEPTED.

Items.push

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

Si vous envoyez un nouvel ID, une nouvelle entrée est ajouté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 annule la réservation des entrées interrogées. Pour en savoir plus sur les entrées réservées et disponibles, consultez la section Items.poll.

Items.push avec hachages

L'API Google Cloud Search permet de spécifier les valeurs de hachage des métadonnées et du contenu dans les requêtes Items.index. Plutôt que de spécifier type, vous pouvez indiquer les valeurs de hachage des métadonnées et/ou du contenu à l'aide d'une requête d'ajout. La file d'attente d'indexation Cloud Search compare les valeurs de hachage fournies avec les valeurs stockées avec l'élément dans la source de données. Si elles ne correspondent pas, l'entrée concernée est marquée comme MODIFIED. Si aucun élément correspondant n'existe dans l'index, l'état de l'élément devient alors NEW_ITEM.

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 sont renvoyées en fonction de leur priorité, indépendamment de la section de file d'attente dans laquelle elles figurent. Chaque entrée renvoyée est réservée et n'est plus renvoyée par les autres appels à Items.poll, jusqu'à ce que l'un des événements suivants se produise:

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