Comment obtenir le nombre de résultats de recherche dans Zoho Desk

La récupération du nombre total de résultats de recherche dans Zoho Desk s'effectue via une seule requête GET vers le point de terminaison de comptage de recherche Desk, nécessitant que le scope OAuth Desk.search.READ soit préalablement autorisé.

Pourquoi c'est important

Lorsque vous créez des tableaux de bord, des automatisations ou des assistants pilotés par l'IA sur Zoho Desk, vous avez souvent besoin de savoir *combien* d'enregistrements correspondent à une requête avant de décider de paginer ou d'afficher un résumé. Connaître le nombre à l'avance évite des récupérations de données inutiles et maintient votre intégration efficace. C'est également la base de toute requête en langage naturel du type « combien de tickets correspondent à X ? » acheminée via une intégration Zoho Desk. En tant que support expert indépendant pour Zoho — et non le support officiel de Zoho — Beam Help vous guide à travers les étapes exactes ci-dessous.

---

Étape par étape

Étape 1. Vérifiez que le scope OAuth correct est accordé.

Avant qu'une opération de recherche puisse réussir, votre token OAuth doit inclure le scope Desk.search.READ. Ce scope se trouve aux côtés d'autres groupes de permissions Desk tels que les tickets, les contacts, les tâches et les paramètres dans la configuration des scopes de votre application. ^[4] Sans lui, l'API rejettera la requête avec une erreur d'autorisation.

Étape 2. Confirmez que votre token couvre la bonne organisation Desk.

Votre session connectée doit contenir les valeurs correctes de deskorgid et desk_portal afin que les requêtes soient acheminées vers le portail Zoho Desk souhaité. ^[8] Si vous travaillez sur plusieurs centres de données (EU, AU, IN, etc.), assurez-vous que l'URL de base reflète le bon domaine régional — par exemple https://desk.zoho.eu plutôt que le domaine par défaut https://desk.zoho.com. ^[8]

Étape 3. Appelez le point de terminaison de comptage de recherche.

Émettez une requête GET vers :

GET /api/v1/search/count

Passez vos paramètres de recherche sous forme de dictionnaire de chaîne de requête (l'argument p dans le wrapper SDK). Le nom de l'opération est getsearchresults_count et elle retourne le nombre total d'enregistrements correspondant à vos critères de recherche. ^[3]

En Python, en utilisant le wrapper client Desk, l'appel ressemble à ceci :

result = desk_client.get_search_results_count(p={"searchStr": "billing issue"})

La méthode émet un GET vers /api/v1/search/count avec les paires clé-valeur que vous fournissez dans p. ^[3]

Étape 4. Traitez la réponse et extrayez le nombre.

L'API retourne un dictionnaire de résultats. Dans un contexte d'assistant IA, un utilitaire tel que extractrecord_count peut analyser ce dictionnaire et retourner un entier simple. ^[5] Si le résultat contient une clé error, traitez-le comme une requête échouée et inspectez le message d'erreur avant de réessayer. ^[5]

Étape 5. (Facultatif) Intégrez le nombre dans la logique en aval.

Une fois que vous disposez du nombre entier, vous pouvez brancher votre logique — par exemple, afficher « Vous avez *N* enregistrements correspondant à ce filtre » à un utilisateur final, ou décider de déclencher une récupération paginée. ^[6] Si le nombre revient comme None ou si le résultat est ambigu, affichez un message de clarification plutôt que d'échouer silencieusement. ^[6]

---

Pièges courants

• Scope Desk.search.READ manquant. C'est la cause la plus fréquente d'une réponse 401 ou 403 sur le point de terminaison de comptage de recherche. Vérifiez que Desk.search.READ est explicitement listé dans votre chaîne de scope OAuth — il n'est pas implicitement inclus par Desk.tickets.ALL ou tout autre groupe. ^{[1] [4]}

• Mauvais portail ou identifiant d'organisation. Si deskportal est défini, il a la priorité sur deskorg_id lors de la construction de l'URL de base. Passer une valeur incorrecte acheminera votre requête vers le mauvais portail et retournera des résultats inattendus ou une erreur 404. ^[8]

• Passer None comme dictionnaire de paramètres. La méthode getsearchresults_count accepte p=None par défaut, mais omettre entièrement les paramètres de recherche peut retourner un nombre pour tous les enregistrements plutôt qu'un sous-ensemble filtré — confirmez que cela correspond à votre intention. ^[3]

• Zoho rejette la requête après une erreur de paramètre. Si l'API retourne un objet d'erreur dans le dictionnaire de résultats, le modèle recommandé est d'afficher un message tel que « Zoho a rejeté la requête — que dois-je ajuster pour pouvoir réessayer ? » plutôt que d'ignorer l'erreur silencieusement. ^[5]

---

Ce qu'il faut vérifier

• Liste des scopes : Vérifiez que Desk.search.READ apparaît dans la chaîne de scope de votre token OAuth actif avant d'effectuer l'appel. ^[4]
• Format de la réponse du point de terminaison : Confirmez que le dictionnaire retourné contient un champ de nombre (et non une clé error) avant de le transmettre à la logique en aval. ^[5]
• Routage portail/organisation : Après un appel réussi, comparez le nombre avec l'interface Zoho Desk à l'adresse https://desk.zoho.{dc}/agent/{portal} pour vous assurer que les résultats appartiennent à la bonne organisation. ^[8]