Freigeben über

Translator v3.0

  • Artikel

Neuigkeiten

Version 3.0 von Translator umfasst eine moderne JSON-basierte Web-API. Sie ermöglicht eine bessere Nutzung und Leistung, indem vorhandene Features zu einer geringeren Zahl von Vorgängen zusammengefasst und neue Features bereitgestellt werden.

  • Transliteration zur Konvertierung von Text in einer Sprache aus einem Skript in ein anderes Skript.
  • Übersetzung in mehrere Sprachen innerhalb einer Anforderung.
  • Spracherkennung, Übersetzung und Transliteration innerhalb einer Anforderung.
  • Wörterbuch zum Nachschlagen von Übersetzungsalternativen für einen Begriff und zum Ermitteln von Rückübersetzungen und Kontextbeispielen für die Begriffe.
  • Informativere Ergebnisse für die Spracherkennung.

Basis-URLs

Anforderungen an Translator werden in den meisten Fällen von dem Rechenzentrum bearbeitet, das dem Ursprungsort der Anforderung am nächsten liegt. Wenn bei Verwendung des globalen Endpunkts ein Rechenzentrumsausfall vorliegt, wird die Anforderung möglicherweise außerhalb der geografischen Region weitergeleitet.

Wenn Sie erzwingen möchten, dass die Anforderung innerhalb einer bestimmten geografischen Region verarbeitet wird, verwenden Sie den gewünschten geografischen Endpunkt. Alle Anforderungen werden zwischen den Rechenzentren innerhalb der geografischen Region 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 unter Dienstendpunkte 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 region Switzerland 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 Translator oder Multi-Service in Azure KI Services, und verwenden Sie Ihren Schlüssel (im Azure-Portal) für die Authentifizierung.

Es gibt drei Header, mit denen Sie Ihr Abonnement authentifizieren können. Diese Tabelle beschreibt, wie jeder verwendet wird:

Header BESCHREIBUNG
Ocp-Apim-Subscription-Key Verwendung mit Azure KI Services-Abonnement, wenn Sie Ihren geheimen Schlüssel übergeben
Der Wert ist der geheime Azure-Schlüssel für Ihr Abonnement für Translator.
Autorisierung Verwendung mit dem Azure KI Services-Abonnement, wenn Sie ein Authentifizierungstoken übergeben
Der Wert ist das Bearertoken: Bearer <token>.
Ocp-Apim-Subscription-Region Verwendung mit einer Ressource für mehrere Dienste und einer regionalen Translator-Ressource
Der Wert ist die Region der Ressource für mehrere Dienste bzw. der regionalen Übersetzerressource. Dieser Wert ist bei Verwendung einer globalen Übersetzerressource optional.

Geheimer Schlüssel

Die erste Option ist die Authentifizierung mithilfe des Headers Ocp-Apim-Subscription-Key. Fügen Sie Ihrer 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 Translator aufzurufen.

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

Hier sehen Sie eine Beispielanforderung zum Aufrufen von Translator mit 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 von Translator benötigen.

Header 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 die Region der Übersetzerressource.

Hier sehen Sie eine Beispielanforderung zum Aufrufen von Translator mit der regionalen Übersetzerressource.

// 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 Ressource für mehrere Dienste

Mit einer Ressource für mehrere Diensten müssen Sie nur einen API-Schlüssel verwenden, um Anforderungen für mehrere Dienste zu authentifizieren.

Wenn Sie einen geheimen Multi-Service-Schlüssel verwenden, müssen Sie Ihrer Anforderung zwei Authentifizierungsheader hinzufügen. Sie benötigen zwei Header, um Translator aufzurufen.

Header BESCHREIBUNG
Ocp-Apim-Subscription-Key Der Wert ist der geheime Azure-Schlüssel für Ihre Ressource für mehrere Dienste.
Ocp-Apim-Subscription-Region Der Wert ist die Region der Ressource für mehrere Dienste.

Die Region ist für das Abonnement der Multi-Service-Text-API erforderlich. Die ausgewählte Region ist die einzige Region, die Sie bei Verwendung des Multi-Service-Schlüssels für die Textübersetzung verwenden können. Dabei muss es sich um die Region handeln, die Sie bei Ihrer Registrierung für das Multi-Service-Abonnement im Azure-Portal ausgewählt haben.

Wenn Sie den geheimen Schlüssel in der Abfragezeichenfolge mit dem Parameter Subscription-Key übergeben, dann müssen Sie die Region mit dem Abfrageparameter Subscription-Region angeben.

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. Senden Sie eine POST-Anforderung an die folgende URL, um ein Autorisierungstoken zu erhalten:

Ressourcentyp Authentifizierungsdienst-URL
Global https://api.cognitive.microsoft.com/sts/v1.0/issueToken
Regional oder für mehrere Dienste https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Hier sind Beispielanforderungen zum Abrufen eines Tokens über einen geheimen Schlüssel für eine globale Ressource angegeben:

// 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>'

Im Folgenden sind Beispielanforderungen zum Abrufen eines Tokens über einen geheimen Schlüssel für eine regionale Ressource in der Region „USA, Mitte“ angegeben:

// 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 im Antworttext im Nur-Text-Format zurück. Das gültige Token wird während der Autorisierung als Bearertoken an den Translator-Dienst übergeben.

Authorization: Bearer <Base64-access_token>

Ein Authentifizierungstoken ist zehn Minuten lang gültig. Das Token sollte wiederverwendet werden, wenn Translator mehrfach aufgerufen wird. Wenn Ihr Programm aber über längere Zeit Anforderungen an Translator sendet, muss das Programm regelmäßig (beispielsweise alle acht Minuten) ein neues Zugriffstoken anfordern.

Authentifizierung mit Microsoft Entra ID

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

Voraussetzungen

Headers

Header Wert
Authorization Der Wert ist ein von Azure AD generiertes Bearertoken für den Zugriff.
  • Das Bearertoken bietet einen Authentifizierungsnachweis und überprüft die Autorisierung des Clients für die Verwendung der Ressource.
  • Ein Authentifizierungstoken ist 10 Minuten lang gültig und sollte wiederverwendet werden, wenn mehrere Aufrufe von Translator erfolgen.
    • Siehe Beispielanforderung: 2. Abrufen eines Tokens
Ocp-Apim-Subscription-Region Der Wert ist die Region der Übersetzerressource.
  • Bei einer globalen Ressource ist dieser Wert optional.
Ocp-Apim-ResourceId Der Wert ist die Ressourcen-ID für Ihre Instanz der Übersetzer-Ressource.
  • Sie finden die Ressourcen-ID im Azure-Portal unter Translator-Ressource → Eigenschaften.
  • Ressourcen-ID-Format:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<Ressourcenname>/
Translator-Eigenschaftenseite – Azure-Portal

Screenshot: Translator-Eigenschaftenseite im Azure-Portal.

Wichtig

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 Ihres 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 zur Verwendung verwalteter Identitäten

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

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 Translator-Dienst ist jetzt mit VNET-Funktionen (virtuelles Netzwerk) in allen Regionen der öffentlichen Azure-Cloud verfügbar. Informationen zum Aktivieren des virtuellen Netzwerks finden Sie unter Konfigurieren virtueller Azure AI-Dienste.

Nachdem Sie diese Funktion aktiviert haben, müssen Sie den benutzerdefinierten Endpunkt zum Aufrufen von Translator verwenden. Die Verwendung des globalen Übersetzerendpunkts (api.cognitive.microsofttranslator.com) und die Authentifizierung mit einem Zugriffstoken sind nicht möglich.

Sie finden den benutzerdefinierten Endpunkt, nachdem Sie eine Übersetzerressource erstellt und den Zugriff von ausgewählten Netzwerken und privaten Endpunkten zugelassen haben.

  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 Einstellungen für das virtuelle Netzwerk im Azure-Portal.

  4. Klicken Sie zum Übernehmen der Änderungen auf Speichern.

  5. Wählen Sie im Abschnitt Ressourcenverwaltungdie Option Schlüssel und Endpunkt aus.

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

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

    Screenshot des Endpunkts des virtuellen Netzwerks.

Header 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 die Region der Übersetzerressource. Bei einer Ressource vom Typ global ist dieser Wert optional.

Hier sehen Sie eine Beispielanforderung zum Aufrufen von Translator mit dem benutzerdefinierten Endpunkt.

// 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?'}]"

Errors

Eine Standardfehlerantwort ist ein JSON-Objekt mit einem Name-Wert-Paar mit dem Namen error. Der Wert ist außerdem ein JSON-Objekt mit Eigenschaften:

  • code: Ein vom Server definierter Fehlercode.
  • message: Eine Zeichenfolge als für Menschen lesbare Darstellung des Fehlers.

Ein Kunde mit einer kostenlose Testversion des Abonnements erhält beispielsweise den folgenden Fehler, nachdem das Kontingent für den Free-Tarif 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:

Code 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 wurde ü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 wurde nicht autorisiert, da die Anmeldeinformationen fehlen oder ungültig sind.
401015 „Die angegebenen Anmeldeinformationen gelten für die SAPI. Diese Anforderung erfordert Anmeldeinformationen für die Text-API. Verwenden Sie ein Abonnement für Translator.“
403000 Der Vorgang ist nicht zulässig.
403001 Der Vorgang ist nicht zulässig, da das kostenlose Kontingent für das Abonnement überschritten wurde.
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 Content-Type-Header fehlt oder ist ungültig.
429000, 429001, 429002 Der Server hat die Anforderung abgelehnt, da der Client die Anforderungsgrenzwerte überschritten hat.
500000 Ein unerwarteter Fehler ist aufgetreten. Wenn der Fehler weiterhin besteht, melden Sie ihn, und geben Sie dabei Folgendes an: Datum und Zeitpunkt des Fehlers, Anforderungsbezeichner aus dem Antwortheader X-RequestId und Clientbezeichner aus dem Anforderungsheader X-ClientTraceId.
503000 Service is temporarily unavailable. (Der Dienst ist vorübergehend nicht verfügbar.) Wiederholen. Wenn der Fehler weiterhin besteht, melden Sie ihn, und geben Sie dabei Folgendes an: Datum und Zeitpunkt des Fehlers, Anforderungsbezeichner aus dem Antwortheader X-RequestId und Clientbezeichner aus dem Anforderungsheader X-ClientTraceId.

Metriken

Metriken ermöglichen es Ihnen, die Informationen über die Nutzung und Verfügbarkeit des Translator im Azure-Portal im Abschnitt „Metriken“ anzuzeigen, wie im folgenden Screenshot gezeigt. Weitere Informationen finden Sie unter Daten- und Plattformmetriken.

Translator-Metriken

In dieser Tabelle sind die verfügbaren Metriken mit einer Beschreibung aufgeführt, wie sie zur Überwachung von Aufrufen der Übersetzungs-API verwendet werden.

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