Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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 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 Ü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-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. 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
Ein kurzes Verständnis der Authentifizierung mit microsoft Entra ID.
Ein kurzes Verständnis der Autorisierung des Zugriffs auf verwaltete Identitäten.
Kopfzeilen
Kopfzeile | Wert |
---|---|
Autorisierung | Der Wert ist ein von Azure AD generiertes Zugriffs bearertoken .
|
Ocp-Apim-Subscription-Region | Der Wert ist der Bereich der Übersetzerressource.
|
Ocp-Apim-ResourceId | Der Wert ist die Ressourcen-ID für Ihre Translator-Ressourceninstanz.
|
Übersetzer-Eigenschaftenseite – 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.
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.
Wählen Sie "Speichern" aus, um Ihre Änderungen anzuwenden.
Wählen Sie "Schlüssel" und "Endpunkt " im Abschnitt "Ressourcenverwaltung " aus.
Wählen Sie die Registerkarte "Virtuelles Netzwerk " aus.
Hier sind die Endpunkte für die Textübersetzung und die Dokumentübersetzung aufgeführt.
Ü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.
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 |