Freigeben über

Translator v3.0

Was ist neu?

Version 3.0 des Übersetzers stellt eine moderne JSON-basierte Web-API bereit. Sie verbessert die Benutzerfreundlichkeit und Leistung, indem vorhandene Features in weniger Vorgänge konsolidiert werden und neue Features bereitgestellt werden.

  • Transliteration zum Konvertieren von Text in einer Sprache von einem Skript in ein anderes Skript.
  • Übersetzung in mehrere Sprachen in einer Anforderung.
  • Spracherkennung, Übersetzung und Transliteration in einer Anforderung.
  • Wörterbuch zum Nachschlagen alternativer Übersetzungen eines Begriffs, um Back-Übersetzungen und Beispiele zu finden, die ausdrücken, die im Kontext verwendet werden.
  • Informativere Spracherkennungsergebnisse.

Basis-URLs

Anforderungen an Übersetzer werden in den meisten Fällen vom Rechenzentrum verarbeitet, das am nächsten ist, an dem die Anforderung stammt. Wenn beim Verwenden des globalen Endpunkts ein Rechenzentrumsfehler auftritt, kann die Anforderung außerhalb der Geografie weitergeleitet werden.

Wenn Sie erzwingen möchten, dass die Anforderung innerhalb einer bestimmten Geografie verarbeitet wird, verwenden Sie den gewünschten geografischen Endpunkt. Alle Anforderungen werden zwischen den Rechenzentren innerhalb der Geografie verarbeitet.

✔️ Feature: Textübersetzung

Dienstendpunkt Rechenzentrum für die Anforderungsverarbeitung
Global (empfohlen):
api.cognitive.microsofttranslator.com		 Nächstgelegenes verfügbares Rechenzentrum.
Nord-, Mittel- und Südamerika:
api-nam.cognitive.microsofttranslator.com		 USA, Osten 2 • USA, Westen 2
Asien-Pazifik:
api-apc.cognitive.microsofttranslator.com		 Japan, Osten • Asien, Südosten
Europa (außer der Schweiz):
api-eur.cognitive.microsofttranslator.com		 Frankreich, Mitte • Europa, Westen
Schweiz:
Weitere Informationen finden Sie unterDienstendpunkte für die Schweiz.		 Schweiz, Norden • Schweiz, Westen

Dienstendpunkte der Schweiz

Kunden mit einer Ressource in „Schweiz, Norden“ oder „Schweiz, Westen“ können sicherstellen, dass ihre Text-API-Anforderungen innerhalb der Schweiz verarbeitet werden. Um sicherzustellen, dass Anforderungen in der Schweiz verarbeitet werden, erstellen Sie die Übersetzerressource in Resource regionSwitzerland North oder Switzerland West. Verwenden Sie dann den benutzerdefinierten Endpunkt der Ressource in Ihren API-Anforderungen.

Beispiel: Wenn Sie im Azure-Portal eine Übersetzerressource mit Resource region als Switzerland North erstellen und Ihre Ressource den Namen „my-swiss-n“ hat, lautet Ihr benutzerdefinierter Endpunkt „https​://my-swiss-n.cognitiveservices.azure.com“. Eine Beispielanforderung für die Übersetzung wäre etwa:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

Die Funktion „Benutzerdefinierter Translator“ ist in der Schweiz derzeit nicht verfügbar.

Authentifizierung

Abonnieren Sie Übersetzer oder Multi-Service in Azure AI-Diensten , und verwenden Sie Ihren Schlüssel (im Azure-Portal verfügbar), um sich zu authentifizieren.

Es gibt drei Header, mit denen Sie Ihr Abonnement authentifizieren können. In dieser Tabelle wird beschrieben, wie jede verwendet wird:

Überschriften BESCHREIBUNG
Ocp-Apim-Subscription-Key Verwenden Sie das Azure AI-Dienstabonnement, wenn Sie Ihren geheimen Schlüssel übergeben.
Der Wert ist der geheime Azure-Schlüssel für Ihr Abonnement für Translator.
Autorisierung Verwenden Sie das Azure AI-Dienstabonnement, wenn Sie ein Authentifizierungstoken übergeben.
Der Wert ist das Bearer-Token: Bearer <token>.
Ocp-Apim-Subscription-Region Verwendung mit Multi-Service- und Regionalübersetzerressource.
Der Wert ist die Region der Ressource für mehrere Dienste oder regionale Übersetzer. Dieser Wert ist optional, wenn eine globale Übersetzerressource verwendet wird.

Geheimer Schlüssel

Die erste Option besteht darin, sich mithilfe des Ocp-Apim-Subscription-Key Headers zu authentifizieren. Fügen Sie der Anforderung den Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> Header hinzu.

Authentifizieren mit einer globalen Ressource

Wenn Sie eine globale Übersetzerressource verwenden, müssen Sie einen Header einschließen, um den Übersetzer aufzurufen.

Überschriften BESCHREIBUNG
Ocp-Apim-Subscription-Key Der Wert ist der geheime Azure-Schlüssel für Ihr Abonnement für Translator.

Hier ist eine Beispielanforderung zum Aufrufen des Übersetzers mithilfe der globalen Übersetzerressource.

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Authentifizieren mit einer regionalen Ressource

Wenn Sie eine regionale Übersetzerressource verwenden, gibt es zwei Header, die Sie zum Aufrufen des Übersetzers benötigen.

Überschriften BESCHREIBUNG
Ocp-Apim-Subscription-Key Der Wert ist der geheime Azure-Schlüssel für Ihr Abonnement für Translator.
Ocp-Apim-Subscription-Region Der Wert ist der Bereich der Übersetzerressource.

Hier ist eine Beispielanforderung zum Aufrufen des Übersetzers mithilfe der Ressource für regionale Übersetzer

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Authentifizieren mit einer Multi-Service-Ressource

Mit einer Multi-Service-Ressource können Sie einen einzelnen API-Schlüssel verwenden, um Anforderungen für mehrere Dienste zu authentifizieren.

Wenn Sie einen Geheimschlüssel mit mehreren Diensten verwenden, müssen Sie zwei Authentifizierungsheader mit Ihrer Anforderung einschließen. Es gibt zwei Header, die Sie zum Aufrufen des Übersetzers benötigen.

Überschriften BESCHREIBUNG
Ocp-Apim-Subscription-Key Der Wert ist der geheime Azure-Schlüssel für Ihre Multi-Service-Ressource.
Ocp-Apim-Subscription-Region Der Wert ist der Bereich der Multi-Service-Ressource.

Region ist für das Text-API-Abonnement mit mehreren Diensten erforderlich. Die von Ihnen ausgewählte Region ist die einzige Region, die Sie für die Textübersetzung verwenden können, wenn Sie den Mehrdienstschlüssel verwenden. Es muss dieselbe Region sein, die Sie ausgewählt haben, wenn Sie sich über das Azure-Portal für Ihr Multi-Service-Abonnement registriert haben.

Wenn Sie den geheimen Schlüssel in der Abfragezeichenfolge mit dem Parameter Subscription-Keyübergeben, müssen Sie den Bereich mit dem Abfrageparameter Subscription-Regionangeben.

Authentifizieren mit einem Zugriffstoken

Alternativ können Sie Ihren geheimen Schlüssel für ein Zugriffstoken austauschen. Dieses Token ist in jeder Anforderung als Authorization Header enthalten. Um ein Autorisierungstoken abzurufen, stellen Sie eine POST Anforderung an die folgende URL:

Ressourcentyp URL des Authentifizierungsdiensts
Weltweit https://api.cognitive.microsoft.com/sts/v1.0/issueToken
Regional oder Multi-Service https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Hier sind Beispielanforderungen zum Abrufen eines Tokens mit einem geheimen Schlüssel für eine globale Ressource:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Und hier finden Sie Beispielanforderungen zum Abrufen eines Tokens mit einem geheimen Schlüssel für eine regionale Ressource, die sich in den USA befindet:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Eine erfolgreiche Anforderung gibt das codierte Zugriffstoken als Nur-Text im Antworttext zurück. Das gültige Token wird als Bearertoken in der Autorisierung an den Übersetzerdienst übergeben.

Authorization: Bearer <Base64-access_token>

Ein Authentifizierungstoken ist 10 Minuten gültig. Das Token sollte bei mehreren Aufrufen des Übersetzers wiederverwendet werden. Wenn Ihr Programm jedoch über einen längeren Zeitraum Anforderungen an den Übersetzer sendet, muss Ihr Programm in regelmäßigen Abständen ein neues Zugriffstoken anfordern (z. B. alle 8 Minuten).

Authentifizierung mit Microsoft Entra ID

Translator v3.0 unterstützt die Microsoft Entra-Authentifizierung, die cloudbasierte Identitäts- und Zugriffsverwaltungslösung von Microsoft. Autorisierungsheader ermöglichen dem Übersetzerdienst zu überprüfen, ob der anfordernde Client berechtigt ist, die Ressource zu verwenden und die Anforderung abzuschließen.

Voraussetzungen

Kopfzeilen

Kopfzeile Wert
Autorisierung Der Wert ist ein von Azure AD generiertes Zugriffs bearertoken .
  • Das Bearertoken stellt einen Authentifizierungsnachweis bereit und überprüft die Autorisierung des Clients für die Verwendung der Ressource.
  • Ein Authentifizierungstoken ist für 10 Minuten gültig und sollte bei mehreren Aufrufen von Translator wiederverwendet werden.
    • SieheBeispielanforderung: 2. Abrufen eines Tokens
Ocp-Apim-Subscription-Region Der Wert ist der Bereich der Übersetzerressource.
  • Dieser Wert ist optional, wenn die Ressource global ist.
Ocp-Apim-ResourceId Der Wert ist die Ressourcen-ID für Ihre Translator-Ressourceninstanz.
  • Sie finden die Ressourcen-ID im Azure-Portal unter Translator Resource → Properties.
  • Ressourcen-ID-Format:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
Übersetzer-Eigenschaftenseite – Azure-Portal

Screenshot:Translator-Eigenschaftenseite im Azure-Portal.

Von Bedeutung

Weisen Sie dem Dienstprinzipal die Rolle " Cognitive Services User " zu. Durch Zuweisen dieser Rolle gewähren Sie dienstprinzipalen Zugriff auf die Übersetzerressource.

Beispiele

Verwenden des globalen Endpunkts

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Verwenden des benutzerdefinierten Endpunkts

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Beispiele für verwaltete Identitäten

Translator v3.0 unterstützt auch die Autorisierung des Zugriffs auf verwaltete Identitäten. Wenn eine verwaltete Identität für eine Übersetzerressource aktiviert ist, können Sie das bearertoken übergeben, das von verwalteter Identität im Anforderungsheader generiert wird.

Mit dem globalen Endpunkt

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Mit Ihrem benutzerdefinierten Endpunkt

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Unterstützung von Virtual Network

Der Übersetzerdienst ist jetzt mit Virtual Network(VNET)-Funktionen in allen Regionen der öffentlichen Azure-Cloud verfügbar. Informationen zum Aktivieren des virtuellen Netzwerks finden Sie unterKonfigurieren virtueller Azure AI-Dienste.

Nachdem Sie diese Funktion aktiviert haben, müssen Sie den benutzerdefinierten Endpunkt verwenden, um den Übersetzer aufzurufen. Sie können den globalen Übersetzerendpunkt ("api.cognitive.microsofttranslator.com") nicht verwenden, und Sie können sich nicht mit einem Zugriffstoken authentifizieren.

Sie können den benutzerdefinierten Endpunkt finden, nachdem Sie eine Übersetzerressource erstellt und den Zugriff von ausgewählten Netzwerken und privaten Endpunkten zulassen.

  1. Navigieren Sie zur Ressource „Translator“ im Azure-Portal.

  2. Wählen Sie im Abschnitt Ressourcenverwaltung die Option Netzwerk aus.

  3. Wählen Sie auf der Registerkarte Firewalls und virtuelle Netzwerke die Option Ausgewählte Netzwerke und private Endpunkte aus.

    Screenshot der Einstellung des virtuellen Netzwerks im Azure-Portal.

  4. Wählen Sie "Speichern" aus, um Ihre Änderungen anzuwenden.

  5. Wählen Sie "Schlüssel" und "Endpunkt " im Abschnitt "Ressourcenverwaltung " aus.

  6. Wählen Sie die Registerkarte "Virtuelles Netzwerk " aus.

  7. Hier sind die Endpunkte für die Textübersetzung und die Dokumentübersetzung aufgeführt.

    Screenshot des virtuellen Netzwerkendpunkts.

Überschriften BESCHREIBUNG
Ocp-Apim-Subscription-Key Der Wert ist der geheime Azure-Schlüssel für Ihr Abonnement für Translator.
Ocp-Apim-Subscription-Region Der Wert ist der Bereich der Übersetzerressource. Dieser Wert ist optional, wenn die Ressource global

Hier ist eine Beispielanforderung zum Aufrufen des Übersetzers mithilfe des benutzerdefinierten Endpunkts.

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Irrtümer

Eine Standardfehlerantwort ist ein JSON-Objekt mit name/value pair named error. Der Wert ist auch ein JSON-Objekt mit Eigenschaften:

  • code: Ein serverdefinierter Fehlercode.
  • message: Eine Zeichenfolge, die eine lesbare Darstellung des Fehlers angibt.

Beispielsweise würde ein Kunde mit einem kostenlosen Testabonnement die folgende Fehlermeldung erhalten, sobald das kostenlose Kontingent erschöpft ist:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

Der Fehlercode ist eine 6-stellige Zahl, die aus dem 3-stelligen HTTP-Statuscode gefolgt von einer 3-stelligen Zahl zur Kategorisierung des Fehlers besteht. Häufige Fehlercodes sind:

Programmcode BESCHREIBUNG
400000 Eine der Anforderungseingaben ist ungültig.
400001 Der scope-Parameter ist ungültig.
400002 Der category-Parameter ist ungültig.
400003 Ein Sprachenspezifizierer fehlt oder ist ungültig.
400004 Ein Zielskriptspezifizierer („To script“) fehlt oder ist ungültig.
400005 Ein Eingabetext fehlt oder ist ungültig.
400006 Die Kombination aus Sprache und Skript ist ungültig.
400018 Ein Quellskriptspezifizierer („From script“) fehlt oder ist ungültig.
400019 Eine der angegebenen Sprachen wird nicht unterstützt.
400020 Eines der Elemente im Array des Eingabetexts ist ungültig.
400021 Der API-Versionsparameter fehlt oder ist ungültig.
400023 Eines der angegebenen Sprachpaare wird nicht unterstützt.
400035 Die Ausgangssprache („Aus“-Feld) ist ungültig.
400036 Der Zielsprache (Feld „To“) fehlt oder ist ungültig.
400042 Eine der angegebenen Optionen („Optionen“-Feld) ist ungültig.
400043 Die Clientablaufverfolgungs-ID (ClientTraceId-Feld oder X-ClientTraceId-Header) fehlt oder ist ungültig.
400050 Der Eingabetext ist zu lang. Informieren Sie sich unter Anforderungsgrenzwerte.
400064 Der translation-Parameter fehlt oder ist ungültig.
400070 Die Anzahl Zielskripts (ToScript-Parameter) entspricht nicht der Anzahl Zielsprachen (To-Parameter).
400071 Der Wert ist für „TextType“ ungültig.
400072 Das Array mit dem Eingabetext enthält zu viele Elemente.
400073 Der Skriptparameter ist ungültig.
400074 Der Text der Anforderung ist kein gültiger JSON-Code.
400075 Die Kombination aus Sprachpaar und Kategorie ist ungültig.
400077 Die maximale Anforderungsgröße wird überschritten. Informieren Sie sich unter Anforderungsgrenzwerte.
400079 Das für die Übersetzung zwischen Ausgangs- und Zielsprache angeforderte benutzerdefinierte System ist nicht vorhanden.
400080 Die Transliteration wird für die Sprache oder das Skript nicht unterstützt.
401000 Die Anforderung ist nicht autorisiert, da Anmeldeinformationen fehlen oder ungültig sind.
401015 "Die bereitgestellten Anmeldeinformationen gelten für die Sprach-API. Für diese Anforderung sind Anmeldeinformationen für die Text-API erforderlich. Verwenden Sie ein Abonnement für Übersetzer."
403000 Der Vorgang ist nicht zulässig.
403001 Der Vorgang ist nicht zulässig, da das Abonnement sein kostenloses Kontingent überschritten hat.
405000 Die Anforderungsmethode wird für die angeforderte Ressource nicht unterstützt.
408001 Das angeforderte Übersetzungssystem wird vorbereitet. Versuchen Sie es in einigen Minuten erneut.
408002 Anforderungstimeout beim Warten auf den eingehenden Datenstrom. Der Client hat innerhalb des Zeitraums, in dem der Server vorbereitet war, zu warten, keine Anforderung erzeugt. Der Client kann die Anforderung ohne Änderungen zu einem späteren Zeitpunkt wiederholen.
415000 Der Inhaltstypheader fehlt oder ist ungültig.
429000, 429001, 429002 Der Server hat die Anforderung abgelehnt, da der Client die Anforderungsgrenzwerte überschritten hat.
500.000 Ein unerwarteter Fehler ist aufgetreten. Wenn der Fehler weiterhin besteht, melden Sie ihn mit Dem Datum/Uhrzeit des Fehlers, der Anforderungs-ID vom Antwortheader X-RequestId und dem Clientbezeichner des Anforderungsheaders X-ClientTraceId.
503000 Service is temporarily unavailable. (Der Dienst ist vorübergehend nicht verfügbar.) und versuchen Sie es erneut. Wenn der Fehler weiterhin besteht, melden Sie ihn mit Dem Datum/Uhrzeit des Fehlers, der Anforderungs-ID vom Antwortheader X-RequestId und dem Clientbezeichner des Anforderungsheaders X-ClientTraceId.

Metriken

Mithilfe von Metriken können Sie die Informationen zur Übersetzernutzung und -verfügbarkeit im Azure-Portal anzeigen. Weitere Informationen finden Sie unter Daten- und Plattformmetriken.

Übersetzermetriken

In dieser Tabelle sind die verfügbaren Metriken aufgeführt, die beschreiben, wie sie zum Überwachen von Übersetzungs-API-Aufrufen verwendet werden.

Metriken BESCHREIBUNG
TotalCalls Gesamtanzahl der API-Aufrufe.
TotalTokenCalls Die Gesamtzahl der API-Aufrufe über den Tokendienst mithilfe des Authentifizierungstokens.
SuccessfulCalls Anzahl erfolgreicher Aufrufe
TotalErrors Anzahl der Anrufe mit Fehlerantwort.
BlockedCalls Anzahl von Aufrufen, die das Raten- oder Kontingentlimit überschritten haben
ServerFehler Anzahl der Anrufe mit internem Serverfehler(5XX).
ClientErrors Anzahl der Anrufe mit clientseitigem Fehler(4XX).
Latenz Dauer zum Abschließen der Anforderung in Millisekunden.
CharactersTranslated Gesamtanzahl von Zeichen in einer eingehenden Textanforderung