Comment appeler l’API REST Analyse de texte

Dans cet article, nous utilisons l’API REST Analyse de texte et Postman pour présenter des concepts clés. L’API fournit plusieurs points de terminaison synchrones et asynchrones pour l’utilisation des fonctionnalités du service.

Créer une ressource Analyse de texte

Notes

  • Si vous souhaitez utiliser les points de terminaison /analyze ou /health, vous aurez besoin d’une ressource d’Analyse de texte utilisant un niveau de tarification Standard (S). Le point de terminaison /analyze est inclus dans votre niveau tarifaire.

Avant d’utiliser l’API Analyse de texte, vous devrez créer une ressource Azure avec une clé et un point de terminaison pour vos applications.

  1. Tout d’abord, accédez au portail Azure et créez une ressource d’Analyse de texte si vous n’en avez pas encore. Choisissez un niveau tarifaire.

  2. Sélectionnez la région que votre point de terminaison doit utiliser.

  3. Créez la ressource Analyse de texte et accédez à la section « Clés et point de terminaison » sous Gestion des ressources dans la partie gauche de la page. Copiez la clé à utiliser ultérieurement lors de l’appel des API. Vous l’ajouterez plus tard en tant que valeur pour l’en-tête Ocp-Apim-Subscription-Key.

  4. Pour vérifier le nombre d’enregistrements de texte qui ont été envoyés à l’aide de votre ressource Analyse de texte :

    1. Accédez à votre ressource Analyse de texte dans le portail Azure.
    2. Cliquez sur Mesures, situées sous Surveillance dans le menu de navigation de gauche.
    3. Sélectionnez Enregistrements de textes traités dans la zone de liste déroulante pour Métrique.

Un enregistrement texte est une unité de texte d’entrée de 1 000 caractères au maximum. Par exemple, 1 500 caractères envoyés en texte d’entrée comptent pour deux enregistrements texte.

Changer votre niveau tarifaire

Si vous disposez d’une ressource Analyse de texte avec un niveau tarifaire compris entre S0 et S4, vous devez la mettre à jour pour utiliser le niveau tarifaire Standard (S). Les niveaux tarifaires S0 à S4 vont être supprimés. Pour mettre à jour le tarif de votre ressource :

  1. Accédez à votre ressource Analyse de texte dans le portail Azure.
  2. Dans le menu de navigation de gauche, sélectionnez Niveau tarifaire. Il se trouve sous GESTION DES RESSOURCES.
  3. Choisissez le niveau tarifaire Standard (S). Puis cliquez sur Sélectionner.

Vous pouvez également créer une ressource Analyse de texte avec le niveau tarifaire Standard (S), et migrer vos applications pour utiliser les informations d’identification de la nouvelle ressource.

Utilisation de l’API de manière asynchrone

Vous pouvez appeler l’API Analyse de texte de façon synchrone (pour des scénarios à faible latence). Vous devez appeler chaque API (fonctionnalité) séparément lors de l’utilisation de l’API synchrone. Si vous devez appeler plusieurs fonctionnalités, consultez la section ci-dessous pour savoir comment appeler l’API Analyse de texte de façon asynchrone.

Utilisation de l’API de manière asynchrone

L’API Analyse de texte v3.1 fournit deux points de terminaison asynchrones :

  • Le point de terminaison /analyze pour l’Analyse de texte vous permet d’analyser le même jeu de documents texte avec plusieurs fonctionnalités d’analyse de texte en un seul appel d’API. Auparavant, pour utiliser plusieurs fonctionnalités, vous deviez effectuer des appels d’API distincts pour chaque opération. Tenez compte de cette fonctionnalité lorsque vous devez analyser de grands ensembles de documents avec plusieurs fonctionnalités d’Analyse de texte.

  • Le point de terminaison /health pour l’Analyse de texte en lien avec la santé, qui peut extraire et étiqueter des informations médicales pertinentes à partir de documents cliniques.

Consultez le tableau ci-dessous pour savoir quelles fonctionnalités vous pouvez utiliser de manière asynchrone. Notez que vous ne pouvez appeler que quelques fonctionnalités à partir du point de terminaison /analyze.

Fonctionnalité Synchrone Asynchrone
Détection de la langue
analyse de sentiments ✔*
Exploration des opinions ✔*
Extraction d’expressions clés ✔*
Reconnaissance d’entité nommée (y compris PII et PHI) ✔*
Liaison d’entités ✔*
Analyse de texte pour la santé (conteneur)
Analyse de texte pour la santé (API)
Synthèse de texte

* - Appelé de façon asynchrone via le point de terminaison /analyze.

Conseil

Pour obtenir une documentation technique détaillée sur l’API et la voir en action, utilisez les liens suivants. Vous pouvez également envoyer des requêtes POST à partir de la console de test de l’API intégrée. Aucune configuration n’est requise, collez simplement votre clé de ressource et vos documents JSON dans la requête :

  • API stable la plus récente – v3.1
  • API stable précédente – v3.0

Quand vous utilisez la fonctionnalité Analyse de texte, les documents de votre requête ne doivent pas dépasser les limites de caractères suivantes. Pour plus d’informations, consultez l’article sur les limites de données.

  • Opérations synchrones et Analyse de texte pour les opérations d’intégrité : 5 120 caractères par document.
  • Opérations asynchrones (analyses) : 125 000 caractères par document.

Formats de demande API

Vous pouvez envoyer des appels synchrones et asynchrones à l’API Analyse de texte.

Demandes synchrones

Le format des demandes d’API est le même pour toutes les opérations synchrones. Les documents sont envoyés dans un objet JSON sous forme de texte brut non structuré. XML n’est pas pris en charge. Le schéma JSON se compose des éléments décrits ci-dessous.

Élément Valeurs valides Requis ? Usage
id Les données dont de type chaîne mais, dans la pratique, les ID de document tendent à être des entiers. Obligatoire Le système utilise les ID que vous fournissez pour structurer la sortie. Des codes langue, phrases clés et scores de sentiment sont générés pour chaque ID dans la demande.
text Texte brut non structuré, jusqu’à 5 120 caractères. Obligatoire Pour la détection de la langue, le texte peut être exprimé dans toute langue. Pour l’analyse des sentiments, l’extraction de phrases clés et l’identification d’entité, le texte doit être dans une langue prise en charge.
language Code ISO 639-1 de 2 caractères d’une langue prise en charge Variable Obligatoire pour l’analyse des sentiments, l’extraction de phrases clés et la liaison d’entité. Facultatif pour la détection de la langue. Son omission ne génère aucune erreur, mais affaiblit l’analyse. Le code de langue doit correspondre au text que vous fournissez.

Voici un exemple de demande API pour les points de terminaison d’Analyse de texte synchrone.

{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "Sample text to be sent to the text analytics api."
    }
  ]
}

Conseil

Pour plus d’informations sur les limites de débits et de taille pour l’envoi de données à l’API Analyse de texte, consultez l’article Limites de données et de débit .

Configurer une demande

Dans Postman (ou un autre outil de test d’API web), ajoutez le point de terminaison pour la fonctionnalité que vous souhaitez utiliser. Utilisez le tableau en dessous pour rechercher le format de point de terminaison approprié, puis remplacez <your-text-analytics-resource> par le point de terminaison de votre ressource. Par exemple :

Conseil

Vous pouvez appeler la version 3.0 des points de terminaison synchrones ci-dessous en remplaçant /v3.1 par /v3.0/.

https://my-resource.cognitiveservices.azure.com/text/analytics/v3.1/languages

Points de terminaison pour l’envoi de demandes synchrones

Fonctionnalité Type de demande Points de terminaison de ressource
Détection de la langue POST <your-text-analytics-resource>/text/analytics/v3.1/languages
Analyse des sentiments POST <your-text-analytics-resource>/text/analytics/v3.1/sentiment
Exploration des opinions POST <your-text-analytics-resource>/text/analytics/v3.1/sentiment?opinionMining=true
Extraction d’expressions clés POST <your-text-analytics-resource>/text/analytics/v3.1/keyPhrases
Reconnaissance d’entité nommée – Général POST <your-text-analytics-resource>/text/analytics/v3.1/entities/recognition/general
Reconnaissance d’entité nommée – PII POST <your-text-analytics-resource>/text/analytics/v3.1/entities/recognition/pii
Reconnaissance d’entité nommée – PHI POST <your-text-analytics-resource>/text/analytics/v3.1/entities/recognition/pii?domain=phi
Liaison d’entités POST <your-text-analytics-resource>/text/analytics/v3.1/entities/linking

Une fois que vous avez votre point de terminaison, dans Postman (ou un autre outil de test d’API web) :

  1. Choisissez le type de demande pour la fonctionnalité que vous souhaitez utiliser.

  2. Collez le point de terminaison de l’opération appropriée souhaitée à partir du tableau ci-dessus.

  3. Définissez les trois en-têtes de demande :

    • Ocp-Apim-Subscription-Key : votre clé d’accès, obtenue à partir du portail Azure
    • Content-Type : application/json
    • Accept : application/json

    Si vous utilisez Postman, votre demande doit ressembler à la capture d’écran suivante, en supposant un point de terminaison /keyPhrases.

    Capture d’écran de demande avec point de terminaison et en-têtes

  4. Choisissez brut pour le format du Corps

    Capture d’écran de demande avec paramètres du corps

  5. Collez des documents JSON dans un format valide. Utilisez les exemples de la section format de demande API ci-dessus et, pour plus d’informations et d’exemples, consultez les rubriques ci-dessous :

Envoyer la demande

Envoyez la demande API. Si vous avez appelé un point de terminaison synchrone, la réponse s’affiche immédiatement, sous la forme d’un document JSON unique, avec un élément pour chaque ID de document fourni dans la demande.

Si vous avez appelé les points de terminaison asynchrones /analyze ou /health, vérifiez que vous avez reçu un code de réponse 202. Vous devrez obtenir la réponse pour afficher les résultats :

  1. Dans la réponse de l’API, recherchez Operation-Location dans l’en-tête, qui identifie le travail que vous avez envoyé à l’API.

  2. Créez une demande GET pour le point de terminaison que vous avez utilisé. Consultez le tableau ci-dessus pour le format du point de terminaison, ainsi que la documentation de référence de l’API. Par exemple :

    https://my-resource.cognitiveservices.azure.com/text/analytics/v3.1/analyze/jobs/<Operation-Location>

  3. Ajoutez Operation-Location à la demande.

  4. La réponse sera un document JSON unique, avec un élément pour chaque ID de document fourni dans la demande.

Notez que pour les opérations asynchrones /analyze ou /health, les résultats de la demande GET à l’étape 2 ci-dessus sont disponibles pendant 24 heures à partir du moment où le travail a été créé. Ce délai est indiqué par la valeur expirationDateTime dans la réponse GET. Après cette période, les résultats sont purgés et ne sont plus disponibles pour récupération.

Exemples de réponses de l’API

Exemples de réponses pour une opération synchrone

Les réponses de point de terminaison synchrone varient en fonction du point de terminaison que vous utilisez. Pour obtenir des exemples de réponses, consultez les articles suivants.

Voir aussi