Verwaltete Identitäten für die Dokumentübersetzung

Artikel
09/03/2024

Verwaltete Identitäten für Azure-Ressourcen sind Dienstprinzipale, die eine Microsoft Entra-Identität und bestimmte Berechtigungen für verwaltete Azure-Ressourcen erstellen. Verwaltete Identitäten sind eine sicherere Möglichkeit, Zugriff auf Speicherdaten zu gewähren, und ersetzen die Anforderung, dass Sie SAS-Token (Shared Access Signature Token) in Ihre Quell- und Ziel-URLs einschließen müssen.

Screenshot: Flow einer verwalteten Identität (RBAC)

Sie können verwaltete Identitäten zur Gewährung des Zugriffs bei einer beliebigen Ressource verwenden, die die Microsoft Entra-Authentifizierung unterstützt. Dies schließt auch Ihre eigenen Anwendungen ein.
Zum Gewähren des Zugriffs auf eine Azure-Ressource weisen Sie einer verwalteten Identität mithilfe der rollenbasierten Zugriffssteuerung von Azure (Azure RBAC) eine Azure-Rolle zu.
Es entstehen keine zusätzlichen Kosten für die Verwendung verwalteter Identitäten in Azure.

Wichtig

Wenn Sie verwaltete Identitäten verwenden, schließen Sie keine SAS-Token-URL in Ihre HTTP-Anforderungen ein – Ihre Anforderungen schlagen sonst fehl. Die Verwendung verwalteter Identitäten ersetzt die Anforderung, dass Sie Shared Access Signature-Token (SAS) in Ihre Quell- und Ziel-URLs einschließen müssen.
Um verwaltete Identitäten für Dokumentübersetzungvorgänge verwenden zu können, müssen Sie Ihre Übersetzerressource in einer bestimmten geografischen Azure-Region erstellen, z. B. USA, Osten. Wenn Ihre Übersetzerressourcenregion auf Global festgelegt ist, können Sie keine verwaltete Identität für die Dokumentübersetzung verwenden. Sie können weiterhin Shared Access Signature-Token (SAS) für die Dokumentübersetzung verwenden.
Dokumentübersetzung wird im S1 Standard Service Plan (nutzungsbasierte Zahlung) sowie in den C2-, C3-, C4- und D3-Volumenrabattplänen unterstützt. Siehe Preise für Azure KI Services – Translator.

Voraussetzungen

Zunächst benötigen Sie Folgendes:

Ein aktives Azure-Konto – Sollten Sie über kein aktives Konto verfügen, können Sie ein kostenloses Konto erstellen.
Eine Textübersetzungsressource für einen einzelnen Dienst (keine Azure KI Services-Ressource für mehrere Dienste), die einer geografischen Region, wie z. B. USA, Westen zugewiesen ist. Ausführliche Schritte finden Sie unter Erstellen einer Azure KI Services-Ressource.
Ein allgemeines Verständnis der rollenbasierten Zugriffssteuerung von Azure (Azure RBAC) unter Verwendung des Azure-Portals
Ein Azure Blob Storage-Konto in derselben Region wie Ihre Textübersetzungsressource. Sie müssen außerdem Container zum Speichern und Organisieren Ihrer Blobdaten unter Ihrem Speicherkonto erstellen.
Wenn sich Ihr Speicherkonto hinter einer Firewall befindet, müssen Sie die folgende Konfiguration aktivieren:
1. Navigieren Sie zum Azure-Portal, und melden Sie sich bei Ihrem Azure-Konto an.
2. Wählen Sie das Speicherkonto aus.
3. Wählen Sie im linken Bereich in der Gruppe Sicherheit und Netzwerk die Option Netzwerk aus.
4. Wählen Sie auf der Registerkarte Firewalls und virtuelle Netzwerke die Option Aktivierung von ausgewählten virtuellen Netzwerken und IP-Adressen aus.
5. Deaktivieren Sie alle Kontrollkästchen.
6. Stellen Sie sicher, dass Microsoft-Netzwerkrouting ausgewählt ist.
7. Wählen Sie im Abschnitt Ressourceninstanzen den Ressourcentyp Microsoft.CognitiveServices/accounts und anschließend Ihre Übersetzerressource als Instanzname aus.
8. Stellen Sie sicher, dass das Kontrollkästchen Azure-Diensten auf der Liste der vertrauenswürdigen Dienste den Zugriff auf dieses Speicherkonto erlauben aktiviert ist. Weitere Informationen zum Verwalten von Ausnahmen finden Sie unter Konfigurieren von Azure Storage-Firewalls und virtuellen Netzwerken.
9. Wählen Sie Speichern aus.
  
  Hinweis
  
  Die Verteilung der Netzwerkänderungen kann bis zu fünf Minuten dauern.
Obwohl der Netzwerkzugriff jetzt zulässig ist, kann Ihre Übersetzerressource nach wie vor nicht auf die Daten in Ihrem Speicherkonto zugreifen. Sie müssen für Ihre Übersetzerressource eine verwaltete Identität erstellen und ihr eine bestimmte Zugriffsrolle zuweisen.

Zuweisungen verwalteter Identitäten

Es gibt zwei Arten von verwalteten Identitäten: systemseitig zugewiesene und benutzerseitig zugewiesene Identitäten. Derzeit unterstützt die Dokumentübersetzung systemseitig zugewiesene verwaltete Identitäten:

Eine systemseitig zugewiesene verwaltete Identität wird direkt für eine Dienstinstanz aktiviert. Sie ist nicht standardmäßig aktiviert. Sie müssen zu Ihrer Ressource wechseln und die Identitätseinstellung aktualisieren.
Die systemseitig zugewiesene verwaltete Identität ist während des gesamten Lebenszyklus an Ihre Ressource gebunden. Wenn Sie Ihre Ressource löschen, wird auch die verwaltete Identität gelöscht.

In den folgenden Schritten aktivieren wir eine systemseitig zugewiesene verwaltete Identität und gewähren Ihrer Textübersetzungsressource begrenzten Zugriff auf Ihr Azure Blob Storage-Konto.

Aktivieren einer systemseitig zugewiesenen verwalteten Identität

Sie müssen der Übersetzerressource Zugriff auf Ihr Speicherkonto gewähren, damit Blobs erstellt, gelesen oder gelöscht werden können. Nachdem Sie die Übersetzerressource mit einer systemseitig zugewiesenen verwalteten Identität aktiviert haben, können Sie die rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) verwenden, um dem Übersetzer Zugriff auf Ihre Azure-Speichercontainer zu gewähren.

Navigieren Sie zum Azure-Portal, und melden Sie sich bei Ihrem Azure-Konto an.
Wählen Sie die Übersetzerressource aus.
Wählen Sie im linken Bereich in der Gruppe Ressourcenverwaltung die Option Identität aus.
Aktivieren Sie auf der Registerkarte Systemseitig zugewiesen die Umschaltfläche Status.

Wichtig

Eine benutzerseitig zugewiesene verwaltete Identität erfüllt die Anforderungen für die Batch-Transkription mit Speicherkonto nicht. Achten Sie darauf, dass Sie eine systemseitig zugewiesene verwaltete Identität aktivieren.
Wählen Sie Speichern aus.

Gewähren von Speicherkontozugriff für Ihre Übersetzerressource

Wichtig

Um eine systemseitig zugewiesene verwaltete Identitätsrolle zuzuweisen, benötigen Sie Microsoft.Authorization/roleAssignments/write-Berechtigungen, z. B Besitzer oder Benutzerzugriffsadministrator, im Speicherbereich für die Speicherressource.

Navigieren Sie zum Azure-Portal, und melden Sie sich bei Ihrem Azure-Konto an.
Wählen Sie die Übersetzerressource aus.
Wählen Sie im linken Bereich in der Gruppe Ressourcenverwaltung die Option Identität aus.
Wählen Sie unter Berechtigungen die Option Azure-Rollenzuweisungen aus:
Wählen Sie auf der Azure-Rollenzuweisungenseite, die geöffnet wird, im Dropdownmenü Ihr Abonnement aus, und wählen Sie dann + Rollenzuweisung hinzufügen aus.
Als Nächstes weisen Sie Ihrer Übersetzerdienstressource die Rolle Mitwirkender an Storage-Blobdaten zu. Mit der Rolle Mitwirkender an Storage-Blobdaten wird der Textübersetzung (repräsentiert durch die systemseitig zugewiesene verwaltete Identität) Lese-, Schreib- und Löschzugriff auf den Blobcontainer und die Daten gewährt. Füllen Sie im Popupfenster Rollenzuweisung hinzufügen die Felder wie folgt aus, und wählen Sie Speichern aus:

Feld Wert

Bereich Storage

Abonnement Das Ihrer Speicherressource zugeordnete Abonnement.

Ressource Der Name Ihrer Speicherressource.

Rolle Mitwirkender an Storage-Blobdaten.
Nachdem die Bestätigungsmeldung Rollenzuweisung hinzugefügt angezeigt wurde, aktualisieren Sie die Seite, um die hinzugefügte Rollenzuweisung zu sehen.
Wenn die neue Rollenzuweisung nicht sofort angezeigt wird, warten Sie. Versuchen Sie dann, die Seite noch einmal zu aktualisieren. Beim Zuweisen oder Entfernen von Rollenzuweisungen kann es bis zu 30 Minuten dauern, bis Änderungen wirksam werden.

Feld	Wert
Bereich	*Storage*
Abonnement	*Das Ihrer Speicherressource zugeordnete Abonnement*.
Ressource	*Der Name Ihrer Speicherressource*.
Rolle	*Mitwirkender an Storage-Blobdaten*.

HTTP-Anforderungen

Eine asynchrone Batchübersetzungsanforderung wird als POST-Anforderung an Ihren Übersetzer-Endpunkt gesendet.
Mit verwalteter Identität und Azure RBAC müssen Sie keine SAS-URLs mehr einfügen.
Wenn der Vorgang erfolgreich ist, gibt die POST-Methode den Antwortcode 202 Accepted zurück, und der Dienst erstellt eine Batchanforderung.
Die übersetzten Dokumente werden in Ihrem Zielcontainer angezeigt.

Header

Jede Anforderung der API für die Dokumentübersetzung enthält die folgenden Header:

HTTP-Header	BESCHREIBUNG
Ocp-Apim-Subscription-Key	Erforderlich: Dieser Wert ist der Azure-Schlüssel für Ihre Übersetzer- oder Azure KI Services-Ressource.
Content-Type	Erforderlich: Gibt den Inhaltstyp der Nutzdaten an. „application/json“ oder „charset=UTF-8“ werden als Werte akzeptiert.

POST-Anforderungstext

Die Anforderungs-URL lautet „POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches“.
Der Anforderungstext ist ein JSON-Objekt mit dem Namen inputs.
Das Objekt inputs enthält die Adressen beider Container sourceURL und targetURL für Ihre Quell- und Zielsprachpaare. Bei einer systemseitig zugewiesenen verwalteten Identität verwenden Sie eine einfache Speicherkonto-URL (ohne SAS oder andere Ergänzungen). Das Format ist https://<storage_account_name>.blob.core.windows.net/<container_name>.
Die Felder prefix und suffix (optional) werden verwendet, um Dokumente im Container zu filtern (einschließlich der Ordner).
Ein Wert für das Feld glossaries (optional) wird angewendet, wenn das Dokument übersetzt wird.
Die targetUrl für die einzelnen Zielsprachen muss jeweils eindeutig sein.

Wichtig

Wenn am Ziel bereits eine Datei mit dem gleichen Namen vorhanden ist, tritt beim Auftrag ein Fehler auf. Wenn Sie verwaltete Identitäten verwenden, schließen Sie keine SAS-Token-URL in Ihre HTTP-Anforderungen ein. Wenn Sie dies tun, schlagen Ihre Anforderungen fehl.

Übersetzen aller Dokumente in einem Container

Dieser Beispielanforderungstext verweist auf einen Quellcontainer für alle Dokumente, die in eine Zielsprache übersetzt werden sollen.

Weitere Informationen finden Sie unter Anforderungsparameter.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>"
                    "language": "fr"
                }
            ]
        }
    ]
}

Übersetzen eines bestimmten Dokuments in einen Container

Dieser Beispielanforderungstext verweist auf ein einzelnes Quelldokument, das in zwei Zielsprachen übersetzt werden soll.

Wichtig

Zusätzlich zu den zuvor erwähnten Anforderungsparametern müssen Sie "storageType": "File" aufnehmen. Andernfalls wird es davon ausgegangen, dass sich die Quell-URL auf Containerebene befindet.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

Übersetzen aller Dokumente in einem Container mithilfe eines benutzerdefinierten Glossars

Dieser Beispielanforderungstext verweist auf einen Quellcontainer für alle Dokumente, die mithilfe eines Glossars in eine Zielsprache übersetzt werden sollen.

Weitere Informationen finden Sie unter Anforderungsparameter.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://<storage_account_name>.blob.core.windows.net/<glossary_container_name>/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Großartig! Sie haben gerade gelernt, wie Sie eine systemseitig zugewiesene verwaltete Identität aktivieren und verwenden. Durch Verwendung der verwalteten Identität für Azure-Ressourcen und Azure RBAC haben Sie der Textübersetzung spezifische Zugriffsrechte für Ihre Speicherressource gewährt, ohne SAS-Token in Ihre HTTP-Anforderungen einzuschließen.

Nächste Schritte

Schnellstart: Erste Schritte bei der Dokumentübersetzung

Tutorial: Zugreifen auf Azure Storage über eine Web-App mit verwalteten Identitäten

Teilen über

Verwaltete Identitäten für die Dokumentübersetzung

Voraussetzungen

Zuweisungen verwalteter Identitäten

Aktivieren einer systemseitig zugewiesenen verwalteten Identität

Gewähren von Speicherkontozugriff für Ihre Übersetzerressource

HTTP-Anforderungen

Header

POST-Anforderungstext

Übersetzen aller Dokumente in einem Container

Übersetzen eines bestimmten Dokuments in einen Container

Übersetzen aller Dokumente in einem Container mithilfe eines benutzerdefinierten Glossars

Nächste Schritte

Feedback

Zusätzliche Ressourcen