Translator v3.0

Artikel
02/15/2024

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.

Gebiet	Basis-URL (geografischer Endpunkt)	Rechenzentren
Global (`non-regional`)	api.cognitive.microsofttranslator.com	Nächstgelegenes verfügbares Rechenzentrum
Asien-Pazifik	api-apc.cognitive.microsofttranslator.com	„Südkorea, Süden“, „Japan, Osten“, „Asien, Südosten“ und „Australien, Osten“
Europa	api-eur.cognitive.microsofttranslator.com	„Europa, Norden“, „Europa, Westen“
USA	api-nam.cognitive.microsofttranslator.com	„USA, Osten“, „USA, Süden-Mitte“, „USA, Westen-Mitte“ und „USA, Westen 2“

¹ 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 Übersetzer Ressource im Resource regionSwitzerland North oder verwenden Switzerland WestSie dann den benutzerdefinierten Endpunkt der Ressource in Ihren API-Anforderungen.

Beispiel: Wenn Sie eine Übersetzer Ressource in Azure-Portal erstellen und Resource regionSwitzerland North ihr Ressourcenname lautetmy-swiss-n, lautet der benutzerdefinierte 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

² Das Feature „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

Grundlegendes in Kürze zur Authentifizierung mit Microsoft Entra ID.
Grundlegendes in Kürze zur Autorisierung des Zugriffs auf verwaltete Identitäten.

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. Informationen hierzu finden Sie unterBeispielanforderung: 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 properties page in the Azure portal.

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 von Virtual Network finden Sie unter Konfigurieren von virtuellen Netzwerken für Azure KI Services.

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.

Navigieren Sie zur Ressource „Translator“ im Azure-Portal.
Wählen Sie im Abschnitt Ressourcenverwaltung die Option Netzwerk aus.
Wählen Sie auf der Registerkarte Firewalls und virtuelle Netzwerke die Option Ausgewählte Netzwerke und private Endpunkte aus.
Klicken Sie zum Übernehmen der Änderungen auf Speichern.
Wählen Sie im Abschnitt Ressourcenverwaltungdie Option Schlüssel und Endpunkt aus.
Wählen Sie die Registerkarte Virtuelles Netzwerk aus.
Dort sind die Endpunkte für Textübersetzung und Dokumentübersetzung aufgeführt.

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 (Feld „ClientTraceId“ oder X-ClientTranceId-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 Metrics

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