Spravované identity pro překlad dokumentů

Článek
02/12/2024

Spravované identity pro prostředky Azure jsou instanční objekty, které vytvářejí identitu Microsoft Entra a konkrétní oprávnění pro spravované prostředky Azure. Spravované identity představují bezpečnější způsob, jak udělit přístup k datům úložiště a nahradit požadavek na zahrnutí tokenů sdíleného přístupového podpisu (SAS) ke zdroji a cílovým adresám URL.

Screenshot of managed identity flow (RBAC).

Spravované identity můžete použít k udělení přístupu k libovolnému prostředku, který podporuje ověřování Microsoft Entra, včetně vlastních aplikací.
Pokud chcete udělit přístup k prostředku Azure, přiřaďte spravované identitě roli Azure pomocí řízení přístupu na základě role v Azure (Azure RBAC).
Používání spravovaných identit v Azure není nijak nákladné.

Důležité

Při použití spravovaných identit nezahrnujte do požadavků HTTP adresu URL tokenu SAS – vaše požadavky selžou. Použití spravovaných identit nahrazuje požadavek na zahrnutí tokenů sdíleného přístupového podpisu (SAS) ke zdrojovým a cílovým adresám URL.
Pokud chcete použít spravované identity pro operace překladu dokumentů, musíte prostředek Služby Translator vytvořit v konkrétní geografické oblasti Azure, jako je USA – východ. Pokud je vaše oblast prostředků Služby Translator nastavená na Globální, nemůžete pro překlad dokumentů použít spravovanou identitu. K překladu dokumentů můžete dál používat tokeny sdíleného přístupového podpisu (SAS ).
Překlad dokumentů je k dispozici pouze v plánu služby S1 Standard (průběžné platby) nebo v plánu D3 Volume Discount Plan. Podívejte se naceny služeb Azure AI – Translator.

Požadavky

Na začátek budete potřebovat:

Aktivní účet Azure – pokud ho nemáte, můžete si vytvořit bezplatný účet.
Prostředek Translator s jednou službou (nikoli služba Azure AI s více službami) přiřazený k geografické oblasti, jako je USA – západ. Podrobné kroky najdete v tématuVytvoření prostředku s více službami.
Stručný přehled řízení přístupu na základě role v Azure (Azure RBAC) pomocí webu Azure Portal.
Účet služby Azure Blob Storage ve stejné oblasti jako váš prostředek Translator. Musíte také vytvořit kontejnery pro ukládání a uspořádání dat objektů blob v rámci účtu úložiště.
Pokud je váš účet úložiště za bránou firewall, musíte povolit následující konfiguraci:
1. Přejděte na Azure Portal a přihlaste se ke svému účtu Azure.
2. Vyberte účet úložiště.
3. V levém podokně skupiny Zabezpečení a sítě vyberte Sítě.
4. Na kartě Brány firewall a virtuální sítě vyberte Povoleno z vybraných virtuálních sítí a IP adres.
5. Zrušte výběr všech zaškrtávacích políček.
6. Ujistěte se, že je vybrané síťové směrování Microsoftu.
7. V části Instance prostředků vyberte jako typ prostředku Microsoft.CognitiveServices/accounts a jako název instance vyberte prostředek Translator.
8. Ujistěte se, že je zaškrtnuté políčko Povolit službám Azure v seznamu důvěryhodných služeb přístup k tomuto účtu úložiště. Další informace o správěvýjimekch
9. Zvolte Uložit.
  
  Poznámka:
  
  Rozšíření změn sítě může trvat až 5 minut.
I když je teď povolený síťový přístup, váš prostředek Služby Translator stále nemůže získat přístup k datům ve vašem účtu úložiště. Potřebujete vytvořit spravovanou identitu pro prostředek Translator a přiřadit konkrétní přístupovou roli .

Přiřazení spravovaných identit

Existují dva typy spravovaných identit: přiřazené systémem a přiřazené uživatelem. Překlad dokumentů v současné době podporuje spravovanou identitu přiřazenou systémem:

Spravovaná identita přiřazená systémem je povolená přímo v instanci služby. Ve výchozím nastavení není povolená; Musíte přejít do svého prostředku a aktualizovat nastavení identity.
Spravovaná identita přiřazená systémem je svázaná s vaším prostředkem během celého životního cyklu. Pokud prostředek odstraníte, odstraní se i spravovaná identita.

V následujícíchkrocích

Povolení spravované identity přiřazené systémem

Abyste mohli vytvářet, číst nebo odstraňovat objekty blob, musíte prostředku Translatoru udělit přístup k vašemu účtu úložiště. Jakmile povolíte prostředek Translatoru se spravovanou identitou přiřazenou systémem, můžete pomocí řízení přístupu na základě role (Azure RBACAzure) udělit službě Translator přístup k vašim kontejnerům úložiště Azure.

Přejděte na Azure Portal a přihlaste se ke svému účtu Azure.
Vyberte prostředek Translator.
Ve skupině Správa prostředků v levém podokně vyberte Identita.
Na kartě Přiřazený systém zapněte přepínač Stav.

Důležité

Spravovaná identita přiřazená uživatelem nesplňuje požadavky pro scénář účtu úložiště dávkového přepisu. Ujistěte se, že jste povolili spravované identity přiřazené systémem.
Zvolte Uložit.

Udělení přístupu k účtu úložiště pro váš prostředek Translator

Důležité

Pokud chcete přiřadit roli spravované identity přiřazené systémem, potřebujete oprávnění Microsoft.Authorization/roleAssignments/write, jako je vlastník nebo uživatelský přístup, Správa istrator v oboru úložiště pro prostředek úložiště.

Přejděte na Azure Portal a přihlaste se ke svému účtu Azure.
Vyberte prostředek Translator.
Ve skupině Správa prostředků v levém podokně vyberte Identita.
V části Oprávnění vyberte přiřazení rolí Azure:
Na stránce přiřazení rolí Azure, která se otevřela, vyberte v rozevírací nabídce své předplatné a pak vyberte + Přidat přiřazení role.

Dále přiřaďte k prostředku služby Translator roli Přispěvatel dat v objektu blob služby Storage. Role Přispěvatel dat objektů blob služby Storage poskytuje službě Translator (reprezentovanou spravovanou identitou přiřazenou systémem) přístup ke čtení, zápisu a odstraňování přístupu ke kontejneru objektů blob a datům. V automaticky otevíraných otevíraných okně Přidat přiřazení role vyplňte pole následujícím způsobem a vyberte Uložit:

Pole	Hodnota
Scope	*Úložiště*:
Předplatné	*Předplatné přidružené k vašemu prostředku* úložiště.
Prostředek	*Název vašeho prostředku* úložiště.
Role	*Přispěvatel* dat objektů blob služby Storage

Screenshot: add role assignments page in the Azure portal.

Po zobrazení potvrzovací zprávy Přidání přiřazení role aktualizujte stránku, aby se zobrazilo přidané přiřazení role.
Pokud nové přiřazení role hned nevidíte, počkejte a zkuste stránku znovu aktualizovat. Když přiřadíte nebo odeberete přiřazení rolí, může trvat až 30 minut, než se změny projeví.

Požadavky HTTP

Požadavek na asynchronní dávkové překlad se odešle do koncového bodu služby Translator prostřednictvím požadavku POST.
U spravované identity už Azure RBACnemusíte zahrnovat adresy URL SAS.
V případě úspěchu metoda POST vrátí 202 Accepted kód odpovědi a služba vytvoří dávkový požadavek.
Přeložené dokumenty se zobrazí v cílovém kontejneru.

Hlavičky

Každá žádost rozhraní DOCUMENT Translation API obsahuje následující hlavičky:

Hlavička HTTP	Popis
Ocp-Apim-Subscription-Key	Povinné: Hodnota je klíč Azure pro váš prostředek služby Translator nebo Azure AI.
Typ obsahu	Povinné: Určuje typ obsahu datové části. Akceptované hodnoty jsou application/json nebo charset=UTF-8.

Text požadavku POST

Adresa URL požadavku je POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
Text požadavku je objekt JSON s názvem inputs.
Objekt inputs obsahuje adresy kontejneru targetURLsourceURL pro páry zdrojového a cílového jazyka. Se spravovanou identitou přiřazenou systémem použijete adresu URL prostého účtu úložiště (bez SAS nebo jiných doplňků). Formát je https://<storage_account_name>.blob.core.windows.net/<container_name>.
Pole prefix a suffix pole (volitelné) slouží k filtrování dokumentů v kontejneru včetně složek.
Při překladu glossaries dokumentu se použije hodnota pole (volitelné).
Pro targetUrl každý cílový jazyk musí být jedinečný.

Důležité

Pokud soubor se stejným názvem již v cíli existuje, úloha selže. Při použití spravovaných identit nezahrnujte do požadavků HTTP adresu URL tokenu SAS. Pokud to uděláte, vaše požadavky selžou.

Překlad všech dokumentů v kontejneru

Tento ukázkový text požadavku odkazuje na zdrojový kontejner pro všechny dokumenty, které se mají přeložit do cílového jazyka.

Další informace najdete v tématuparametry požadavku.

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

Překlad konkrétního dokumentu v kontejneru

Tento ukázkový text požadavku odkazuje na jeden zdrojový dokument, který se má přeložit do dvou cílových jazyků.

Důležité

Kromě parametrů požadavku, které jste si poznamenali dříve, musíte zahrnout "storageType": "File". Jinak se předpokládá, že zdrojová adresa URL je na úrovni kontejneru.

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

Překlad všech dokumentů v kontejneru pomocí vlastního glosáře

Tento ukázkový text požadavku odkazuje na zdrojový kontejner pro všechny dokumenty, které se mají přeložit do cílového jazyka pomocí glosáře.

Další informace najdete v tématuparametry požadavku.

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

Výborně! Právě jste se dozvěděli, jak povolit a používat spravovanou identitu přiřazenou systémem. Se spravovanou identitou pro prostředky Azure a Azure RBACjste udělili službě Translator specifická přístupová práva k vašemu prostředku úložiště bez zahrnutí tokenů SAS s vašimi požadavky HTTP.

Další kroky

Rychlý start: Začínáme s překladem dokumentů

Kurz: Přístup ke službě Azure Storage z webové aplikace pomocí spravovaných identit

Spravované identity pro překlad dokumentů

Požadavky

Přiřazení spravovaných identit

Povolení spravované identity přiřazené systémem

Udělení přístupu k účtu úložiště pro váš prostředek Translator

Požadavky HTTP

Hlavičky

Text požadavku POST

Překlad všech dokumentů v kontejneru

Překlad konkrétního dokumentu v kontejneru

Překlad všech dokumentů v kontejneru pomocí vlastního glosáře

Další kroky

Další materiály