Asynchrones Verwenden von Sprachdienstfeatures

  • Artikel

Mit dem Sprachdienst können Sie API-Anforderungen asynchron senden, indem Sie entweder die REST-API oder die Clientbibliothek verwenden. Sie können auch mehrere verschiedene Sprachdienstmerkmale in Ihre Anfrage aufnehmen, die gleichzeitig an Ihren Daten durchgeführt werden sollen.

Derzeit stehen die folgenden Features zur asynchronen Verwendung zur Verfügung:

  • Entitätsverknüpfung
  • Dokumentzusammenfassung
  • Konversationszusammenfassung
  • Schlüsselwortextraktion
  • Spracherkennung
  • Erkennung benannter Entitäten (NER)
  • Erkennung von Kundeninhalten
  • Standpunktanalyse und Opinion Mining
  • Textanalyse für Gesundheit
  • Personenbezogene Informationen (Personal Identifiable Information, PII)

Wenn Sie asynchrone Anfragen senden, fallen Gebühren an, die sich nach der Anzahl der Textdatensätze richten, die Sie in Ihre Anfrage aufnehmen, und zwar für jede verwendete Funktion. Wenn Sie beispielsweise einen Textdatensatz für die Sentiment-Analyse und NER senden, wird dies als Senden von zwei Textdatensätzen gezählt, und Sie werden für beide entsprechend Ihrer Preisstufe belastet.

Senden eines asynchronen Auftrags mithilfe der REST-API

Um einen asynchronen API-Auftrag zu senden, lesen Sie die Referenzdokumentation für den JSON-Text, den Sie in Ihrer Anforderung senden.

  1. Fügen Sie dem -Objekt Ihre Dokumente analysisInput hinzu.
  2. Fügen Sie in das Objekt tasks die Operationen ein, die Sie mit Ihren Daten durchführen möchten. Wenn Sie beispielsweise eine Stimmungsanalyse durchführen möchten, fügen Sie das Objekt SentimentAnalysisLROTask ein.
  3. Optional haben Sie auch folgende Möglichkeiten:
    1. Wählen Sie eine bestimmte Version des Modells, das Sie für Ihre Daten verwendet haben.
    2. Nehmen Sie zusätzliche Sprachdienstfunktionen in das tasks-Objekt auf, die gleichzeitig mit Ihren Daten ausgeführt werden sollen.

Sobald Sie den JSON-Body für Ihre Anfrage erstellt haben, fügen Sie Ihren Schlüssel zum Ocp-Apim-Subscription-Key-Header hinzu. Senden Sie dann Ihre API-Anforderung an den Auftragerstellungsendpunkt. Beispiel:

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

Bei einem erfolgreichen Aufruf wird ein Antwortcode 202 zurückgegeben. Die operation-location in der Kopfzeile der Antwort ist der URL, den Sie zum Abrufen der API-Ergebnisse verwenden werden. Der Wert sieht etwa wie die folgende URL aus:

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

Zum Abrufen des Status und der Ergebnisse der Anfrage senden Sie eine GET-Anfrage an die URL, welche Sie in der operation-location-Kopfzeile der vorherigen API-Antwort erhalten haben. Denken Sie daran, Ihren Schlüssel in Ocp-Apim-Subscription-Key einzuschließen. Die Antwort enthält die Ergebnisse Ihres API-Aufrufs.

Senden von asynchronen API-Anforderungen mit der Client-Bibliothek

Stellen Sie zunächst sicher, dass Sie die Client-Bibliothek für die gewünschte Sprache installiert haben. Schritte zum Installieren der Clientbibliothek finden Sie im Schnellstartartikel für das Feature, das Sie verwenden möchten.

Verwenden Sie anschließend das Clientobjekt, um asynchrone Aufrufe an die API zu senden. Die zu verwendenden Methodenaufrufe variieren je nach Sprache. Verwenden Sie die verfügbaren Beispiele und die Referenzdokumentation, um Ihnen den Einstieg zu erleichtern.

Ergebnisverfügbarkeit

Wenn Sie dieses Feature asynchron verwenden, sind die API-Ergebnisse ab der Erfassung der Anforderung wie in der Antwort angegeben 24 Stunden lang verfügbar. Nach diesem Zeitraum werden die Ergebnisse endgültig gelöscht und stehen nicht mehr zum Abruf zur Verfügung.

Automatische Sprachenerkennung

Ab Version 2022-07-01-preview der REST-API können Sie die automatische Spracherkennung für Ihre Dokumente anfordern. Durch Festlegen des language-Parameters auf auto wird der erkannte Sprachcode des Texts als Sprachwert in der Antwort zurückgegeben. Diese Sprachenerkennung verursacht keine zusätzlichen Gebühren für Ihre Sprachressource.

Datengrenzwerte

Hinweis

  • Wenn Sie größere Dokumente analysieren müssen, als der Grenzwert zulässt, können Sie den Text in kleinere Textabschnitte aufteilen, bevor Sie ihn an die API senden.
  • Ein Dokument ist eine einzelne aus Textzeichen bestehende Zeichenfolge.

Sie können bis zu 125.000 Zeichen über alle Dokumente in der asynchronen Anforderung hinweg senden, wie von StringInfo.LengthInTextElements gemessen. Diese Zeichengrenze ist höher als die Grenze für synchrone Anfragen, um einen höheren Durchsatz zu ermöglichen.

Wenn ein Dokument die Zeichengrenze überschreitet, weist die API die gesamte Anfrage zurück und gibt einen Fehler 400 bad request zurück, wenn ein Dokument darin die maximal zulässige Größe überschreitet.

Weitere Informationen