Authentifizierung und Autorisierung

Jede Anforderung an ein Foundry Tool muss einen Authentifizierungsheader enthalten. Dieser Header übergibt einen Ressourcenschlüssel oder ein Authentifizierungstoken, mit dem Ihr Abonnement für einen Dienst oder eine Gruppe von Diensten überprüft wird. In diesem Artikel erfahren Sie, wie Sie eine Anforderung und die Anforderungen für jede Anforderung authentifizieren können.

• Authentifizieren mit einem regionalen, single-service-globalen oder Multi-Service-Ressourcenschlüssel.
• Authentifizieren mit einem Bearertoken.
• Die Authentifizierung mit Microsoft Entra ID ist eine cloudbasierte Identitätslösung, die zum Verwalten des Benutzerzugriffs und der Berechtigungen für Microsoft-Dienste, -Ressourcen und -Anwendungen entwickelt wurde. Mit der Microsoft Entra-ID können Sie Anforderungen an Ihre Azure-Ressourcen authentifizieren, ohne dass Kennwörter oder Schlüssel erforderlich sind.

Überschriften

Abonnieren Sie Übersetzer oder Multi-Service in Foundry Tools, 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:

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.

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.

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.

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:

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 an den Übersetzer als Bearertoken in der Autorisierung ü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 Übersetzer 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.

Microsoft Entra ID-Header

Übersetzer-Eigenschaftenseite – 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 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 Übersetzer ist jetzt mit den Funktionen des virtuellen Netzwerks (VNET) in allen Regionen der öffentlichen Azure-Cloud verfügbar. Informationen zum Aktivieren des virtuellen Netzwerks finden Sie unterConfiguring Foundry Tools virtual networks.

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.

   

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.

   

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