Guide pratique pour utiliser les fonctionnalités du service Language de manière asynchrone

  • Article

Le service de langage vous permet d’envoyer des demandes d’API de manière asynchrone, à l’aide de l’API REST ou de la bibliothèque de client. Vous pouvez également inclure plusieurs fonctionnalités différentes du service de langage dans votre demande, à exécuter simultanément sur vos données.

Actuellement, les fonctionnalités suivantes sont disponibles pour être utilisées de manière asynchrone :

  • Liaison d’entités
  • Résumé du document
  • Résumé de conversation
  • Extraction d’expressions clés
  • Détection de la langue
  • Reconnaissance d’entité nommée (NER)
  • Détection de contenu client
  • Analyse des sentiments et exploration des opinions
  • Analyse de texte pour la santé
  • Informations d’identification personnelle (PII)

Quand vous envoyez des demandes asynchrones, des frais vous sont facturés en fonction du nombre d’enregistrements texte que vous incluez dans votre demande, pour chaque utilisation de fonctionnalité. Par exemple, si vous envoyez un enregistrement texte pour l’analyse des sentiments et pour la reconnaissance d’entité nommée, il sera compté comme envoi de deux enregistrements texte, et vous serez facturé pour les deux, conformément à votre niveau tarifaire.

Soumettre un travail asynchrone à l’aide de l’API REST

Pour soumettre un travail asynchrone, consultez la documentation de référence pour le corps JSON que vous enverrez dans votre requête.

  1. Ajoutez vos documents à l’objet analysisInput.
  2. Dans l’objet tasks, incluez les opérations que vous souhaitez effectuer sur vos données. Par exemple, si vous souhaitez effectuer une analyse des sentiments, vous devez inclure l’objet SentimentAnalysisLROTask.
  3. Vous pouvez éventuellement :
    1. Choisissez une version spécifique du modèle utilisé sur vos données.
    2. Incluez des fonctionnalités de service de langage supplémentaires dans l’objet tasks, à exécuter simultanément sur vos données.

Une fois que vous avez créé le corps JSON de votre demande, ajoutez votre clé à l’en-tête Ocp-Apim-Subscription-Key. Envoyez ensuite votre requête d’API au point de terminaison de création du travail. Par exemple :

POST https://your-endpoint.cognitiveservices.azure.com/language/analyze-text/jobs?api-version=2022-05-01

Un appel réussi retourne un code de réponse 202. La valeur operation-location dans l’en-tête de réponse sera l’URL que vous allez utiliser pour récupérer les résultats de l’API. La valeur ressemblera à l’URL suivante :

GET {Endpoint}/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-05-01

Pour obtenir l’état et récupérer les résultats de la requête, envoyez une requête GET à l’URL que vous avez reçue dans l’en-tête operation-location à partir de la réponse de l’API précédente. N’oubliez pas d’inclure votre clé dans Ocp-Apim-Subscription-Key. La réponse inclut les résultats de votre appel d’API.

Envoyer des demandes d’API asynchrones à l’aide de la bibliothèque de client

Tout d’abord, assurez-vous que la bibliothèque de client est installée pour le langage de votre choix. Pour plus d’instructions sur l’installation de la bibliothèque de client, consultez l’article du guide de démarrage rapide concernant la fonctionnalité que vous souhaitez utiliser.

Ensuite, utilisez l’objet client pour envoyer des appels asynchrones à l’API. Les appels de méthode à utiliser varient en fonction de votre langage. Pour bien démarrer, utilisez les exemples disponibles et la documentation de référence.

Disponibilité des résultats

Lors de l’utilisation de cette fonctionnalité de manière asynchrone, les résultats de l’API sont disponibles pendant 24 heures à partir du moment où la requête a été ingérée, et sont indiqués dans la réponse. Après cette période, les résultats sont purgés et ne sont plus disponibles pour récupération.

Détection de langue automatique

À partir de la version 2022-07-01-preview de l’API REST, vous pouvez demander la détection de langue automatique pour vos documents. En affectant au paramètre language la valeur auto, le code de langue détecté pour le texte est retourné en tant que valeur de langue dans la réponse. Cette détection de langue n’entraîne pas de frais supplémentaires pour votre ressource Language.

Limites de données

Notes

  • Si vous avez besoin d’analyser des documents plus volumineux que la limite autorisée, vous pouvez scinder le texte en blocs de texte plus petits avant de les envoyer à l’API.
  • Un document est une chaîne unique de caractères de texte.

Vous pouvez envoyer jusqu’à 125 000 caractères sur tous les documents contenus dans la requête asynchrone, comme mesuré par StringInfo.LengthInTextElements. Cette limite de caractères est supérieure à la limite des requêtes synchrones, afin de permettre un débit plus élevé.

Si un document dépasse la limite de caractères, l’API rejette l’intégralité de la demande et retourne une erreur 400 bad request.

Voir aussi