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

Artykuł
09/01/2024

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.

Zrzut ekranu przedstawiający przepływ tożsamości zarządzanej (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.
Korzystanie z tożsamości zarządzanych na platformie Azure nie wiąże się z żadnymi dodatkowymi kosztami.

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 obsługiwane w planach usług standardowych S1 (płatność zgodnie z rzeczywistym użyciem) i C2, C3, C4 i D3 w planach rabatów zbiorczych. Zobacz Cennik 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, zobacz Create an Azure AI services resource (Tworzenie zasobu usług AI platformy Azure).
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.
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, zobacz Konfigurowanie zapór i sieci wirtualnych usługi Azure Storage.
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.

Przejdź do witryny Azure Portal i zaloguj się na swoje konto platformy Azure.
Wybierz zasób translatora.
W grupie Zarządzanie zasobami w okienku po lewej stronie wybierz pozycję Tożsamość.
Na karcie Przypisane przez system włącz przełącznik Stan .

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.
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 Administrator dostępu użytkowników w zakresie magazynu dla zasobu magazynu.

Przejdź do witryny Azure Portal i zaloguj się na swoje konto platformy Azure.
Wybierz zasób translatora.
W grupie Zarządzanie zasobami w okienku po lewej stronie wybierz pozycję Tożsamość.
W obszarze Uprawnienia wybierz pozycję Przypisania ról platformy Azure:
Na otwartej stronie Przypisania ról platformy Azure wybierz swoją subskrypcję z menu rozwijanego, a następnie wybierz pozycję + Dodaj przypisanie roli.
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.
Po wyświetleniu komunikatu potwierdzenia Dodano przypisanie roli odśwież stronę, aby wyświetlić dodane przypisanie roli.
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ć.

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

Żą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, zobacz parametry żą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, zobacz parametry żą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

Udostępnij za pośrednictwem

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

Wymagania wstępne

Przypisania tożsamości zarządzanej

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

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

Żądania HTTP

Nagłówki

Treść żądania POST

Tłumaczenie wszystkich dokumentów w kontenerze

Tłumaczenie określonego dokumentu w kontenerze

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

Następne kroki

Opinia

Dodatkowe zasoby