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

• 12/17/2020
• 9 Minuten Lesedauer
• • a
  • o
  • a
  • O

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

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.

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

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.

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

{
    "displayName": "My Job",
    "analysisInput": {
        "documents": [
            {
                "id": "doc1",
                "text": "It's incredibly sunny outside! I'm so happy"
            },
            {
                "id": "doc2",
                "text": "Pike place market is my favorite Seattle attraction."
            }
        ]
    },
    "tasks": {
        "entityRecognitionTasks": [
            {
                "parameters": {
                    "model-version": "latest",
                    "stringIndexType": "TextElements_v8"
                }
            }
        ],
        "keyPhraseExtractionTasks": [{
            "parameters": {
                "model-version": "latest"
            }
        }],
        "entityRecognitionPiiTasks": [{
            "parameters": {
                "model-version": "latest"
            }
        }]
    }
}

example.json

{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "Subject was administered 100mg remdesivir intravenously over a period of 120 min"
    }
  ]
}

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

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.

   

4. Wählen Sie raw (Unformatiert) als Format für Body (Textkörper) aus.Choose raw for the format of the 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:

   • SprachenerkennungLanguage detection
   • SchlüsselbegriffserkennungKey phrase extraction
   • StandpunktanalyseSentiment analysis
   • EntitätserkennungEntity recognition

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

Weitere InformationenSee also

• Übersicht über die TextanalyseText Analytics overview
• Häufig gestellte Fragen (FAQ)Frequently asked questions (FAQ)
  
• Textanalysen (Produktseite)Text Analytics product page
• Verwenden der Textanalyse-ClientbibliothekUsing the Text Analytics client library
• NeuigkeitenWhat's new