Tożsamości zarządzane na potrzeby tłumaczenia dokumentów

  • Artykuł

Tożsamości zarządzane dla zasobów platformy Azure to jednostki usługi, które tworzą tożsamość firmy Microsoft Entra i określone uprawnienia dla zasobów zarządzanych platformy Azure. Tożsamości zarządzane to bezpieczniejszy sposób udzielania dostępu do danych magazynu i zastępowania wymagań dotyczących dołączania tokenów sygnatury dostępu współdzielonego (SAS) do źródłowych i docelowych adresów URL.

Screenshot of managed identity flow (RBAC).

  • Tożsamości zarządzane umożliwiają udzielanie dostępu do dowolnego zasobu obsługującego uwierzytelnianie firmy Microsoft Entra, w tym własnych aplikacji.

  • Aby udzielić dostępu do zasobu platformy Azure, przypisz rolę platformy Azure do tożsamości zarządzanej przy użyciu kontroli dostępu opartej na rolach (Azure RBAC)platformy Azure.

  • Nie ma żadnych dodatkowych kosztów korzystania z tożsamości zarządzanych na platformie Azure.

Ważne

  • W przypadku korzystania z tożsamości zarządzanych nie dołączaj adresu URL tokenu SAS do żądań HTTP — żądania kończą się niepowodzeniem. Użycie tożsamości zarządzanych zastępuje wymaganie uwzględnienia tokenów sygnatury dostępu współdzielonego (SAS) przy użyciu źródłowych i docelowych adresów URL.

  • Aby używać tożsamości zarządzanych na potrzeby operacji tłumaczenia dokumentów, musisz utworzyć zasób usługi Translator w określonym regionie geograficznym platformy Azure, takim jak Wschodnie stany USA. Jeśli region zasobu usługi Translator jest ustawiony na Globalny, nie można użyć tożsamości zarządzanej na potrzeby tłumaczenia dokumentów. Nadal można używać tokenów sygnatury dostępu współdzielonego (SAS) na potrzeby tłumaczenia dokumentów.

  • Tłumaczenie dokumentów jest dostępne tylko w planie S1 Standard Service (płatność zgodnie z rzeczywistym użyciem) lub w planie rabatu zbiorczego D3. ZobaczCennik usług Azure AI — Translator.

Wymagania wstępne

Aby rozpocząć pracę, potrzebne będą następujące elementy:

  • Aktywne konto platformy Azure — jeśli go nie masz, możesz utworzyć bezpłatne konto.

  • Zasób usługi Translator z jedną usługą (a nie wielosługową usługą Azure AI) przypisany do regionu geograficznego, takiego jak Zachodnie stany USA. Aby uzyskać szczegółowe instrukcje, zobaczTworzenie zasobu z wieloma usługami.

  • Krótka wiedza na temat kontroli dostępu opartej na rolach (Azure RBAC) platformy Azure przy użyciu witryny Azure Portal.

  • Konto usługi Azure Blob Storage w tym samym regionie co zasób usługi Translator. Należy również utworzyć kontenery do przechowywania i organizowania danych obiektów blob na koncie magazynu.

  • Jeśli konto magazynu znajduje się za zaporą, należy włączyć następującą konfigurację:

    1. Przejdź do witryny Azure Portal i zaloguj się na swoje konto platformy Azure.

    2. Wybierz konto magazynu.

    3. W grupie Zabezpieczenia i sieć w okienku po lewej stronie wybierz pozycję Sieć.

    4. Na karcie Zapory i sieci wirtualne wybierz pozycję Włączone z wybranych sieci wirtualnych i adresów IP.

      Screenshot: Selected networks radio button selected.

    5. Usuń zaznaczenie wszystkich pól wyboru.

    6. Upewnij się, że wybrano routing sieciowy firmy Microsoft.

    7. W sekcji Wystąpienia zasobów wybierz pozycję Microsoft.CognitiveServices/accounts jako typ zasobu i wybierz zasób usługi Translator jako nazwę wystąpienia.

    8. Upewnij się, że pole Zezwalaj usługom platformy Azure na liście zaufanych usług na dostęp do tego konta magazynu jest zaznaczone. Aby uzyskać więcej informacji na temat zarządzania wyjątkami, zobaczKonfigurowanie zapór i sieci wirtualnych usługi Azure Storage.

      Screenshot: allow trusted services checkbox, portal view.

    9. Wybierz pozycję Zapisz.

      Uwaga

      Propagacja zmian sieci może potrwać do 5 minut.

    Mimo że dostęp sieciowy jest teraz dozwolony, zasób usługi Translator nadal nie może uzyskać dostępu do danych na koncie usługi Storage. Musisz utworzyć tożsamość zarządzaną i przypisać określoną rolę dostępu do zasobu usługi Translator.

Przypisania tożsamości zarządzanej

Istnieją dwa typy tożsamości zarządzanych: przypisane przez system i przypisane przez użytkownika. Obecnie tłumaczenie dokumentów obsługuje tożsamość zarządzaną przypisaną przez system:

  • Tożsamość zarządzana przypisana przez system jest włączona bezpośrednio w wystąpieniu usługi. Nie jest ona domyślnie włączona; Musisz przejść do zasobu i zaktualizować ustawienie tożsamości.

  • Tożsamość zarządzana przypisana przez system jest powiązana z zasobem w całym cyklu życia. Jeśli usuniesz zasób, tożsamość zarządzana zostanie również usunięta.

W poniższych krokach włączymy tożsamość zarządzaną przypisaną przez system i przyznamy zasobowi usługi Translator ograniczony dostęp do konta usługi Azure Blob Storage.

Włączanie tożsamości zarządzanej przypisanej przez system

Aby móc tworzyć, odczytywać lub usuwać obiekty blob, musisz udzielić dostępu do zasobu usługi Translator na konto magazynu. Po włączeniu zasobu usługi Translator z tożsamością zarządzaną przypisaną przez system możesz użyć kontroli dostępu opartej na rolach platformy Azure (Azure RBAC), aby zapewnić usłudze Translator dostęp do kontenerów usługi Azure Storage.

  1. Przejdź do witryny Azure Portal i zaloguj się na swoje konto platformy Azure.

  2. Wybierz zasób translatora.

  3. W grupie Zarządzanie zasobami w okienku po lewej stronie wybierz pozycję Tożsamość.

  4. Na karcie Przypisane przez system włącz przełącznik Stan .

    Screenshot: resource management identity tab in the Azure portal.

    Ważne

    Tożsamość zarządzana przypisana przez użytkownika nie spełnia wymagań scenariusza konta magazynu transkrypcji wsadowej. Pamiętaj, aby włączyć tożsamość zarządzaną przypisaną przez system.

  5. Wybierz pozycję Zapisz.

Udzielanie dostępu do konta magazynu dla zasobu usługi Translator

Ważne

Aby przypisać przypisaną przez system rolę tożsamości zarządzanej, musisz mieć uprawnienia Microsoft.Authorization/roleAssignments/write, takie jak właściciel lub dostęp użytkowników Administracja istrator w zakresie magazynu dla zasobu magazynu.

  1. Przejdź do witryny Azure Portal i zaloguj się na swoje konto platformy Azure.

  2. Wybierz zasób translatora.

  3. W grupie Zarządzanie zasobami w okienku po lewej stronie wybierz pozycję Tożsamość.

  4. W obszarze Uprawnienia wybierz pozycję Przypisania ról platformy Azure:

    Screenshot: enable system-assigned managed identity in Azure portal.

  5. Na otwartej stronie Przypisania ról platformy Azure wybierz swoją subskrypcję z menu rozwijanego, a następnie wybierz pozycję + Dodaj przypisanie roli.

    Screenshot: Azure role assignments page in the Azure portal.

  6. Następnie przypisz rolę Współautor danych obiektu blob usługi Storage do zasobu usługi Translator. Rola Współautor danych obiektu blob usługi Storage zapewnia usłudze Translator (reprezentowane przez tożsamość zarządzaną przypisaną przez system) odczyt, zapis i usuwanie dostępu do kontenera obiektów blob i danych. W oknie podręcznym Dodawanie przypisania roli wypełnij pola w następujący sposób i wybierz pozycję Zapisz:

    Pole Wartość
    Scope Magazyn.
    Subskrypcja Subskrypcja skojarzona z zasobem magazynu.
    Zasób Nazwa zasobu magazynu.
    Rola Współautor danych obiektu blob usługi Storage.

    Screenshot: add role assignments page in the Azure portal.

  7. Po wyświetleniu komunikatu potwierdzenia Dodano przypisanie roli odśwież stronę, aby wyświetlić dodane przypisanie roli.

    Screenshot: Added role assignment confirmation pop-up message.

  8. Jeśli od razu nie widzisz nowego przypisania roli, poczekaj i spróbuj odświeżyć stronę ponownie. Po przypisaniu lub usunięciu przypisań ról może upłynąć do 30 minut, aby zmiany zaczęły obowiązywać.

    Screenshot: Azure role assignments window.

Żądania HTTP

  • Żądanie asynchronicznego tłumaczenia wsadowego jest przesyłane do punktu końcowego usługi Translator za pośrednictwem żądania POST.

  • W przypadku tożsamości zarządzanej i Azure RBACfunkcji nie trzeba już dołączać adresów URL sygnatur dostępu współdzielonego.

  • Jeśli operacja powiedzie się, metoda POST zwraca 202 Accepted kod odpowiedzi, a usługa tworzy żądanie wsadowe.

  • Przetłumaczone dokumenty są wyświetlane w kontenerze docelowym.

Nagłówki

Następujące nagłówki są dołączane do każdego żądania interfejsu API tłumaczenia dokumentów:

Nagłówek HTTP opis
Ocp-Apim-Subscription-Key Wymagane: wartość jest kluczem platformy Azure dla zasobu usług Translator lub Azure AI.
Typ zawartości Wymagane: określa typ zawartości ładunku. Akceptowane wartości to application/json lub charset=UTF-8.

Treść żądania POST

  • Adres URL żądania to POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Treść żądania jest obiektem JSON o nazwie inputs.
  • Obiekt inputs zawiera zarówno adresy kontenerów, jak sourceURL i targetURL dla par językowych źródłowych i docelowych. W przypadku tożsamości zarządzanej przypisanej przez system używasz zwykłego adresu URL konta magazynu (bez sygnatury dostępu współdzielonego lub innych dodatków). Format to https://<storage_account_name>.blob.core.windows.net/<container_name>.
  • Pola prefix i suffix (opcjonalnie) służą do filtrowania dokumentów w kontenerze, w tym folderów.
  • Wartość glossaries pola (opcjonalnie) jest stosowana podczas tłumaczenia dokumentu.
  • Wartość targetUrl dla każdego języka docelowego musi być unikatowa.

Ważne

Jeśli plik o tej samej nazwie już istnieje w miejscu docelowym, zadanie zakończy się niepowodzeniem. W przypadku korzystania z tożsamości zarządzanych nie dołączaj adresu URL tokenu SAS do żądań HTTP. Jeśli to zrobisz, żądania zakończy się niepowodzeniem.

Tłumaczenie wszystkich dokumentów w kontenerze

Ta przykładowa treść żądania odwołuje się do kontenera źródłowego dla wszystkich dokumentów, które mają zostać przetłumaczone na język docelowy.

Aby uzyskać więcej informacji, zobaczparametry żądania.

{
    "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"
                }
            ]
        }
    ]
}

Tłumaczenie określonego dokumentu w kontenerze

Ta przykładowa treść żądania odwołuje się do pojedynczego dokumentu źródłowego, który ma zostać przetłumaczony na dwa języki docelowe.

Ważne

Oprócz zanotowanych wcześniej parametrów żądania należy uwzględnić element "storageType": "File". W przeciwnym razie przyjmuje się, że źródłowy adres URL jest na poziomie kontenera.

{
    "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"
                }
            ]
        }
    ]
}

Tłumaczenie wszystkich dokumentów w kontenerze przy użyciu niestandardowego słownika

Ta przykładowa treść żądania odwołuje się do kontenera źródłowego dla wszystkich dokumentów, które mają zostać przetłumaczone na język docelowy przy użyciu słownika.

Aby uzyskać więcej informacji, zobaczparametry żądania.

{
    "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"
                        }
                    ]
                }
            ]
        }
    ]
}

Świetnie! Wiesz już, jak włączyć tożsamość zarządzaną przypisaną przez system i używać jej. W przypadku tożsamości zarządzanej dla zasobów platformy Azure i Azure RBACprogramu przyznano usłudze Translator określone prawa dostępu do zasobu magazynu bez dołączania tokenów SAS do żądań HTTP.

Następne kroki

Szybki start: wprowadzenie do tłumaczenia dokumentów

Samouczek: uzyskiwanie dostępu do usługi Azure Storage z poziomu aplikacji internetowej przy użyciu tożsamości zarządzanych