Aufrufen der Textanalyse-REST-APIHow to call the Text Analytics REST API

In diesem Artikel werden mithilfe der Textanalyse-REST-API und Postman wichtige Konzepte veranschaulicht.In this article, we use the Text Analytics REST API and Postman to demonstrate key concepts. Die API bietet mehrere synchrone und asynchrone Endpunkte für die Verwendung der Dienstfeatures.The API provides several synchronous and asynchronous endpoints for using the features of the service.

Erstellen einer TextanalyseressourceCreate a Text Analytics resource

Hinweis

  • Sie benötigen eine Ressource der Textanalyse mit einem Tarif des Typs „Standard (S)“, wenn Sie die Endpunkte /analyze oder /health verwenden möchten.You will need a Text Analytics resource using a Standard (S) pricing tier if you want to use the /analyze or /health endpoints. Der /analyze-Endpunkt ist in Ihrem Tarif enthalten.The /analyze endpoint is included in your pricing tier.

Bevor Sie die Textanalyse-API verwenden, müssen Sie eine Azure-Ressource mit einem Schlüssel und Endpunkt für Ihre Anwendungen erstellen.Before you use the Text Analytics API, you will need to create a Azure resource with a key and endpoint for your applications.

  1. Melden Sie sich zunächst im Azure-Portal an, und erstellen Sie eine neue Ressource der Textanalyse, sofern Sie noch keine haben.First, go to the Azure portal and create a new Text Analytics resource, if you don't have one already. Wählen Sie einen Tarif aus.Choose a pricing tier.

  2. Wählen Sie die Region aus, die Sie für Ihren Endpunkt verwenden möchten.Select the region you want to use for your endpoint. Beachten Sie, dass die Endpunkte /analyze und /health nur in den folgenden Regionen verfügbar sind: USA, Westen 2; USA, Osten 2; USA, Mitte; Europa, Norden; Europa, Westen.Please note the /analyze and /health endpoints are only available in the following regions: West US 2, East US 2, Central US, North Europe and West Europe.

  3. Erstellen Sie die Ressource der Textanalyse, und wechseln Sie links auf der Seite zum Blatt mit den Schlüsseln und Endpunkten.Create the Text Analytics resource and go to the “keys and endpoint blade” in the left of the page. Kopieren Sie den Schlüssel, mit dem Sie später die APIs aufrufen werden.Copy the key to be used later when you call the APIs. Sie werden ihn später als Wert für den Header Ocp-Apim-Subscription-Key hinzufügen.You'll add this later as a value for the Ocp-Apim-Subscription-Key header.

Ändern des TarifsChange your pricing tier

Wenn Sie über eine Textanalyseressource mit einem der Tarife S0 bis S4 verfügen, können Sie den Tarif so aktualisieren, dass der Tarif „Standard (S)“ verwendet wird:If you have an existing Text Analytics resource using the S0 through S4 pricing tier, you can update it to use the Standard (S) pricing tier:

  1. Navigieren Sie im Azure-Portal zur Textanalyseressource.Navigate to your Text Analytics resource in the Azure portal.
  2. Klicken Sie im Navigationsmenü auf der linken Seite auf Tarif.Select Pricing tier in the left navigation menu. Die Option befindet sich unter RESSOURCENVERWALTUNG.It will be below RESOURCE MANAGEMENT.
  3. Wählen Sie als Tarif „Standard (S)“ aus.Choose the Standard (S) pricing tier. Klicken Sie dann auf Auswählen.Then click Select.

Sie können auch eine neue Textanalyseressource mit Tarif „Standard (S)“ erstellen und Ihre Anwendungen migrieren, sodass die Anmeldeinformationen für die neue Ressource verwendet werden.You can also create a new Text Analytics resource with the Standard (S) pricing tier, and migrate your applications to use the credentials for the new resource.

Synchrones Verwenden der APIUsing the API synchronously

Sie können die Textanalyse-API synchron aufrufen (Szenarios mit geringer Latenz).You can call Text Analytics synchronously (for low latency scenarios). Sie müssen jede API (Feature) einzeln aufrufen, wenn Sie die API synchron verwenden.You have to call each API (feature) separately when using synchronous API. Wenn Sie mehrere Features aufrufen müssen, sehen Sie sich den Abschnitt unten an, wie Sie die Textanalyse-API asynchron aufrufen.If you need to call multiple features then check out below section on how to call Text Analytics asynchronously.

Asynchrones Verwenden der APIUsing the API asynchronously

Ab Version „v3.1-preview.3“ stellt die Textanalyse-API zwei asynchrone Endpunkte bereit:Starting in v3.1-preview.3, the Text Analytics API provides two asynchronous endpoints:

  • Mit dem Endpunkt /analyze für die Textanalyse können Sie dieselben Textdokumente mit mehreren Textanalysefeatures in einem einzigen API-Aufruf analysieren.The /analyze endpoint for Text Analytics allows you to analyze the same set of text documents with multiple text analytics features in one API call. Bisher mussten Sie für jeden Vorgang separate API-Aufrufe durchführen, um mehrere Features verwenden zu können.Previously, to use multiple features you would need to make separate API calls for each operation. Denken Sie an diese Funktion, wenn Sie große Mengen von Dokumenten mit mehr als einem Textanalyse-Feature analysieren müssen.Consider this capability when you need to analyze large sets of documents with more than one Text Analytics feature.

  • Mit dem Endpunkt /health für die Textanalyse für das Gesundheitssystem können relevante medizinische Informationen aus klinischen Dokumenten extrahiert und gekennzeichnet werden.The /health endpoint for Text Analytics for health, which can extract and label relevant medical information from clinical documents.

In der folgenden Tabelle wird gezeigt, welche Features asynchron verwendet werden können.See the table below to see which features can be used asynchronously. Beachten Sie, dass nur einige wenige Features über den Endpunkt /analyze aufgerufen werden können.Note that only a few features can be called from the /analyze endpoint.

FunktionFeature SynchronSynchronous AsynchronAsynchronous
SpracherkennungLanguage detection
StimmungsanalyseSentiment analysis
Opinion MiningOpinion mining
SchlüsselwortextraktionKey phrase extraction ✔*✔*
Erkennung benannter Entitäten (einschließlich personenbezogener Informationen und geschützter Gesundheitsdaten)Named Entity Recognition (including PII and PHI) ✔*✔*
Textanalyse für das Gesundheitssystem (Container)Text Analytics for health (container)
Textanalyse für das Gesundheitssystem (API)Text Analytics for health (API)

*: wird asynchron über den /analyze-Endpunkt aufgerufen* - Called asynchronously through the /analyze endpoint.

Tipp

Unter den folgenden Links finden Sie eine ausführliche technische Dokumentation zur API und können sie in Aktion erleben.For detailed API technical documentation and to see it in action, use the following links. Sie können auch POST-Anforderungen über die integrierte API-Testkonsole senden.You can also send POST requests from the built-in API test console. Es ist keine Einrichtung erforderlich. Fügen Sie einfach den Ressourcenschlüssel und die JSON-Dokumente in die Anforderung ein:No setup is required, simply paste your resource key and JSON documents into the request:

API-AnforderungsformateAPI request formats

Sie können sowohl synchrone als auch asynchrone Aufrufe an die Textanalyse-API senden.You can send both synchronous and asynchronous calls to the Text Analytics API.

Synchrone AnforderungenSynchronous requests

Das Format für API-Anforderungen ist für alle synchronen Vorgänge identisch.The format for API requests is the same for all synchronous operations. Dokumente werden als unformatierter, unstrukturierter Text in einem JSON-Objekt übermittelt.Documents are submitted in a JSON object as raw unstructured text. XML wird nicht unterstützt.XML is not supported. Das JSON-Schema besteht aus den folgenden Elementen.The JSON schema consists of the elements described below.

ElementElement Gültige WerteValid values Erforderlich?Required? VerwendungUsage
id Der Datentyp ist „Zeichenfolge“ (string), aber in der Praxis sind Dokument-IDs eher ganze Zahlen (integer).The data type is string, but in practice document IDs tend to be integers. ErforderlichRequired Das System verwendet die IDs, die Sie angeben, um die Ausgabe zu strukturieren.The system uses the IDs you provide to structure the output. Sprachcodes, Schlüsselbegriffe und Stimmungspunktzahlen werden für jede ID in der Anforderung generiert.Language codes, key phrases, and sentiment scores are generated for each ID in the request.
text Unstrukturierter, unformatierter Text mit bis zu 5.120 Zeichen.Unstructured raw text, up to 5,120 characters. ErforderlichRequired Für die Erkennung der Sprache kann der Text in einer beliebigen Sprache ausgedrückt werden.For language detection, text can be expressed in any language. Für die Standpunktanalyse, Schlüsselbegriffserkennung und Entitätsidentifikation muss der Text in einer unterstützten Sprache sein.For sentiment analysis, key phrase extraction and entity identification, the text must be in a supported language.
language Aus 2 Zeichen bestehender ISO 639-1-Code für eine unterstützte Sprache2-character ISO 639-1 code for a supported language VariesVaries Erforderlich für die Standpunktanalyse, Schlüsselbegriffserkennung und Entitätsverknüpfung, optional für die Sprachenerkennung.Required for sentiment analysis, key phrase extraction, and entity linking; optional for language detection. Es gibt keinen Fehler, wenn Sie sie ausschließen, aber die Analyse wird ohne geschwächt.There is no error if you exclude it, but the analysis is weakened without it. Der Sprachcode sollte dem von Ihnen bereitgestellten text entsprechen.The language code should correspond to the text you provide.

Der folgende Code ist ein Beispiel einer API-Anforderung für die synchronen Endpunkte der Textanalyse.The following is an example of an API request for the synchronous Text Analytics endpoints.

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

Tipp

Informationen zu den Raten- und Größenbeschränkungen für das Senden von Daten an die Textanalyse-API finden Sie im Artikel Daten- und Ratenbeschränkungen.See the Data and rate limits article for information on the rates and size limits for sending data to the Text Analytics API.

Einrichten einer AnforderungSet up a request

Fügen Sie in Postman (oder einem anderen Web-API-Testtool) den Endpunkt für das gewünschte Feature hinzu.In Postman (or another web API test tool), add the endpoint for the feature you want to use. Ermitteln Sie mithilfe der folgende Tabelle das richtige Endpunktformat, und ersetzen Sie <your-text-analytics-resource> durch Ihren Ressourcenendpunkt.Use the table below to find the appropriate endpoint format, and replace <your-text-analytics-resource> with your resource endpoint. Zum Beispiel:For example:

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

Endpunkte für das Senden synchroner AnforderungenEndpoints for sending synchronous requests

FunktionFeature AnforderungstypRequest type RessourcenendpunkteResource endpoints
SpracherkennungLanguage detection POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/languages
StimmungsanalyseSentiment analysis POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/sentiment
Opinion MiningOpinion Mining POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/sentiment?opinionMining=true
SchlüsselwortextraktionKey phrase extraction POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/keyPhrases
Erkennung benannter Entitäten – allgemeinNamed entity recognition - general POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/general
Erkennung benannter Entitäten – personenbezogene InformationenNamed entity recognition - PII POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/pii
Erkennung benannter Entitäten – geschützte GesundheitsdatenNamed entity recognition - PHI POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/pii?domain=phi

Wenn Sie Ihren Endpunkt haben, gehen Sie wie folgt in Postman (oder einem anderen Web-API-Testtool) vor:After you have your endpoint, in Postman (or another web API test tool):

  1. Wählen Sie den Anforderungstyp für das gewünschte Feature aus.Choose the request type for the feature you want to use.

  2. Fügen Sie den Endpunkt des gewünschten Vorgangs aus der obigen Tabelle ein.Paste in the endpoint of the proper operation you want from the above table.

  3. Legen Sie die drei Anforderungsheader fest:Set the three request headers:

    • Ocp-Apim-Subscription-Key: Ihr aus dem Azure-Portal abgerufener ZugriffsschlüsselOcp-Apim-Subscription-Key: your access key, obtained from Azure portal
    • Content-Type: application/jsonContent-Type: application/json
    • Accept: application/jsonAccept: application/json

    Wenn Sie Postman verwenden, sollte Ihre Anforderung bei einem /keyPhrases-Endpunkt in etwa wie im folgenden Screenshot aussehen.If you're using Postman, your request should look similar to the following screenshot, assuming a /keyPhrases endpoint.

    Screenshot der Anforderung mit Endpunkt und Headern

  4. Wählen Sie raw (Unformatiert) als Format für Body (Textkörper) aus.Choose raw for the format of the Body

    Screenshot der Anforderung mit Textkörpereinstellungen (body)

  5. Fügen Sie einige JSON-Dokumente in einem gültigen Format ein.Paste in some JSON documents in a valid format. Verwenden Sie die Beispiele im Abschnitt API-Anforderungsformat weiter oben. Weitere Informationen und Beispiele finden Sie in den folgenden Themen:Use the examples in the API request format section above, and for more information and examples, see the topics below:

Senden der AnforderungSend the request

Senden Sie die API-Anforderung.Submit the API request. Wenn Sie einen synchronen Endpunkt aufgerufen haben, wird die Antwort sofort als einzelnes JSON-Dokument mit einem Element für jede Dokument-ID angezeigt, die in der Anforderung angegeben ist.If you made the call to a synchronous endpoint, the response will be displayed immediately, as a single JSON document, with an item for each document ID provided in the request.

Wenn Sie die asynchronen Endpunkte /analyze oder /health aufgerufen haben, überprüfen Sie, ob Sie einen 202-Antwortcode erhalten haben.If you made the call to the asynchronous /analyze or /health endpoints, check that you received a 202 response code. Sie müssen die Antwort abrufen, um die Ergebnisse anzuzeigen:you will need to get the response to view the results:

  1. Suchen Sie Operation-Location im Header der API-Antwort, der den Auftrag identifiziert, den Sie an die API gesendet haben.In the API response, find the Operation-Location from the header, which identifies the job you sent to the API.

  2. Erstellen Sie eine GET-Anforderung für den verwendeten Endpunkt.Create a GET request for the endpoint you used. In der obigen Tabelle finden Sie das Endpunktformat. Außerdem sollten Sie die Referenzdokumentation zur API lesen.refer to the table above for the endpoint format, and review the API reference documentation. Zum Beispiel:For example:

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

  3. Fügen Sie der Anforderung den Wert von Operation-Location hinzu.Add the Operation-Location to the request.

  4. Die Antwort ist ein einzelnes JSON-Dokument, das für jede in der Anforderung angegebene Dokument-ID ein Element enthält.The response will be a single JSON document, with an item for each document ID provided in the request.

Beachten Sie, dass für beide asynchronen /analyze- oder /health-Vorgänge die Ergebnisse der GET-Anforderung in Schritt 2 oben für 24 Stunden ab dem Zeitpunkt der Erstellung des Auftrags zur Verfügung stehen.Please note that for both asynchronous /analyze or /health operations, the results from the GET request in step 2 above are available for 24 hours from the time the job was created. Diese Zeit wird durch den expirationDateTime-Wert in der GET-Antwort angegeben.This time is indicated by the expirationDateTime value in the GET response. Nach diesem Zeitraum werden die Ergebnisse endgültig gelöscht und stehen nicht mehr zum Abruf zur Verfügung.After this time period, the results are purged and are no longer available for retrieval.

Beispiel-API-AntwortenExample API responses

Beispielantworten für synchrone VorgängeExample responses for synchronous operation

Die Antworten der synchronen Endpunkte variieren je nach verwendetem Endpunkt.The synchronous endpoint responses will vary depending on the endpoint you use. In den folgenden Artikeln finden Sie einige Antwortbeispiele.See the following articles for example responses.

Weitere InformationenSee also