Beheerde identiteiten voor documentomzetting

Beheerde identiteiten voor Azure-resources zijn service-principals die een Microsoft Entra-identiteit en specifieke machtigingen voor door Azure beheerde resources maken. Beheerde identiteiten zijn een veiligere manier om toegang te verlenen tot opslaggegevens en om de vereiste voor het opnemen van sas-tokens (Shared Access Signature) te vervangen door uw bron- en doel-URL's.

• U kunt beheerde identiteiten gebruiken om toegang te verlenen tot elke resource die ondersteuning biedt voor Microsoft Entra-verificatie, inclusief uw eigen toepassingen.

• Als u toegang wilt verlenen tot een Azure-resource, wijst u een Azure-rol toe aan een beheerde identiteit met behulp van op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC).

• Er zijn geen extra kosten verbonden aan het gebruik van beheerde identiteiten in Azure.

Belangrijk

• Wanneer u beheerde identiteiten gebruikt, neemt u geen SAS-token-URL op met uw HTTP-aanvragen. Uw aanvragen mislukken. Als u beheerde identiteiten gebruikt, wordt de vereiste voor het opnemen van sas-tokens (Shared Access Signature) vervangen door uw bron- en doel-URL's.

• Als u beheerde identiteiten wilt gebruiken voor documentomzettingsbewerkingen, moet u uw Translator-resource maken in een specifieke geografische Azure-regio, zoals VS - oost. Als uw Translator-resourceregio is ingesteld op Globaal, kunt u geen beheerde identiteit gebruiken voor documentomzetting. U kunt nog steeds SAS-tokens (Shared Access Signature) gebruiken voor documentomzetting.

• Documentvertaling wordt ondersteund in het S1 Standard-serviceabonnement (betalen per gebruik) en C2-, C3-, C4- en D3-volumekortingsplannen. Zie prijzen voor Azure AI-services: Translator.

Vereisten

Om aan de slag te gaan, hebt u het volgende nodig:

• Een actief Azure-account: als u er nog geen hebt, kunt u een gratis account maken.

• Een Translator met één service (geen Azure AI-services met meerdere services) die is toegewezen aan een geografische regio, zoals VS - west. Zie Een multiserviceresource maken voor gedetailleerde stappen.

• Een kort begrip van op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) met behulp van Azure Portal.

• Een Azure Blob Storage-account in dezelfde regio als uw Translator-resource. U moet ook containers maken om uw blobgegevens in uw opslagaccount op te slaan en te organiseren.

• Als uw opslagaccount zich achter een firewall bevindt, moet u de volgende configuratie inschakelen:

  1. Ga naar Azure Portal en meld u aan bij uw account.

  2. Selecteer het opslagaccount.

  3. Selecteer Netwerken in de groep Beveiliging en netwerken in het linkerdeelvenster.

  4. Selecteer op het tabblad Firewalls en virtuele netwerken de optie Ingeschakeld in geselecteerde virtuele netwerken en IP-adressen.

     

  5. Schakel alle selectievakjes uit.

  6. Zorg ervoor dat Microsoft-netwerkroutering is geselecteerd.

  7. Selecteer in de sectie Resource-exemplaren Microsoft.CognitiveServices/accounts als het resourcetype en selecteer uw Translator-resource als de naam van het exemplaar.

  8. Zorg ervoor dat het selectievakje Azure-services toestaan in de lijst met vertrouwde services voor toegang tot dit opslagaccount is ingeschakeld. Zie Azure Storage-firewalls en virtuele netwerken configureren voor meer informatie over het beheren van uitzonderingen.

     

  9. Selecteer Opslaan.

     Notitie

     Het kan tot 5 minuten duren voordat de netwerkwijzigingen zijn doorgegeven.

  Hoewel netwerktoegang nu is toegestaan, heeft uw Translator-resource nog steeds geen toegang tot de gegevens in uw opslagaccount. U moet een beheerde identiteit maken voor en een specifieke toegangsrol toewijzen aan uw Translator-resource.

Toewijzingen van beheerde identiteiten

Er zijn twee typen beheerde identiteiten: door het systeem toegewezen en door de gebruiker toegewezen. Documentvertaling ondersteunt momenteel door het systeem toegewezen beheerde identiteit:

• Een door het systeem toegewezen beheerde identiteit wordt rechtstreeks ingeschakeld op een service-exemplaar. Deze functie is niet standaard ingeschakeld; u moet naar uw resource gaan en de identiteitsinstelling bijwerken.

• De door het systeem toegewezen beheerde identiteit is gedurende de gehele levenscyclus gekoppeld aan uw resource. Als u uw resource verwijdert, wordt de beheerde identiteit ook verwijderd.

In de volgende stappen schakelen we een door het systeem toegewezen beheerde identiteit in en verlenen we uw Translator-resource beperkte toegang tot uw Azure Blob Storage-account.

Een door het systeem toegewezen beheerde identiteit inschakelen

U moet de Translator-resource toegang verlenen tot uw opslagaccount voordat u blobs kunt maken, lezen of verwijderen. Zodra u de Translator-resource hebt ingeschakeld met een door het systeem toegewezen beheerde identiteit, kunt u op rollen gebaseerd toegangsbeheer vanAzure RBAC Azure () gebruiken om Translator toegang te geven tot uw Azure-opslagcontainers.

1. Ga naar Azure Portal en meld u aan bij uw account.

2. Selecteer de Translator-resource.

3. Selecteer Identiteit in de groep Resourcebeheer in het linkerdeelvenster.

4. Schakel op het tabblad Door systeem toegewezen de wisselknop Status in.

   

   Belangrijk

   Door de gebruiker toegewezen beheerde identiteit voldoet niet aan de vereisten voor het opslagaccountscenario voor batchtranscriptie. Zorg ervoor dat je een door het systeem toegewezen beheerde identiteit inschakelt.

5. Selecteer Opslaan.

Opslagaccounttoegang verlenen voor uw Translator-resource

Belangrijk

Als u een door het systeem toegewezen beheerde identiteit wilt toewijzen, hebt u Microsoft.Authorization/roleAssignments/write-machtigingen nodig, zoals Eigenaar of Beheerder voor gebruikerstoegang in het opslagbereik voor de opslagresource.

1. Ga naar Azure Portal en meld u aan bij uw account.

2. Selecteer de Translator-resource.

3. Selecteer Identiteit in de groep Resourcebeheer in het linkerdeelvenster.

4. Selecteer onder Machtigingen Azure-roltoewijzingen:

   

5. Kies op de pagina Azure-roltoewijzingen die zijn geopend uw abonnement in de vervolgkeuzelijst en selecteer vervolgens + Roltoewijzing toevoegen.

   

6. Wijs vervolgens de rol Inzender voor opslagblobgegevens toe aan uw Translator-serviceresource. De rol Inzender voor opslagblobgegevens geeft Translator (vertegenwoordigd door de door het systeem toegewezen beheerde identiteit) lees-, schrijf- en verwijdertoegang tot de blobcontainer en -gegevens. Vul in het pop-upvenster Roltoewijzing toevoegen de velden als volgt in en selecteer Opslaan:

   Veld	Waarde
   Scope	Opslag.
   Abonnement	Het abonnement dat is gekoppeld aan uw opslagresource.
   Resource	De naam van uw opslagresource.
   - Rol	Inzender voor Opslagblobgegevens.

   

7. Nadat het bevestigingsbericht voor roltoewijzing toegevoegd wordt weergegeven, vernieuwt u de pagina om de toegevoegde roltoewijzing te zien.

   

8. Als u de nieuwe roltoewijzing niet meteen ziet, wacht u en vernieuwt u de pagina opnieuw. Wanneer u roltoewijzingen toewijst of verwijdert, kan het tot 30 minuten duren voordat wijzigingen van kracht worden.

   

HTTP-aanvragen

• Een asynchrone batchomzettingsaanvraag wordt via een POST-aanvraag verzonden naar uw Translator-service-eindpunt.

• Met een beheerde identiteit en Azure RBAChoeft u geen SAS-URL's meer op te nemen.

• Als dit lukt, retourneert de POST-methode een 202 Accepted antwoordcode en maakt de service een batchaanvraag.

• De vertaalde documenten worden weergegeven in uw doelcontainer.

Kopteksten

De volgende headers zijn opgenomen in elke api-aanvraag voor documentomzetting:

HTTP-header	Beschrijving
Ocp-Apim-Subscription-Key	Vereist: De waarde is de Azure-sleutel voor uw Translator- of Azure AI-servicesresource.
Inhoudstype	Vereist: Hiermee geeft u het inhoudstype van de nettolading op. Geaccepteerde waarden zijn application/json of charset=UTF-8.

Hoofdtekst POST-aanvraag

• De aanvraag-URL is POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
• De hoofdtekst van de aanvraag is een JSON-object met de naam inputs.
• Het inputs object bevat zowel containeradressen sourceURL voor de bron- als targetURL doeltaalparen. Met door het systeem toegewezen beheerde identiteit gebruikt u een gewone URL van het opslagaccount (geen SAS of andere toevoegingen). De indeling is https://<storage_account_name>.blob.core.windows.net/<container_name>.
• De prefix velden suffix (optioneel) worden gebruikt voor het filteren van documenten in de container, inclusief mappen.
• Er wordt een waarde voor het glossaries veld (optioneel) toegepast wanneer het document wordt vertaald.
• De targetUrl voor elke doeltaal moet uniek zijn.

Belangrijk

Als er al een bestand met dezelfde naam in de bestemming bestaat, mislukt de taak. Wanneer u beheerde identiteiten gebruikt, moet u geen SAS-token-URL met uw HTTP-aanvragen opnemen. Als u dit doet, mislukken uw aanvragen.

Alle documenten in een container vertalen

Deze voorbeeldaanvraagtekst verwijst naar een broncontainer voor alle documenten die moeten worden vertaald naar een doeltaal.

Zie aanvraagparameters voor meer informatie.

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

Een specifiek document vertalen in een container

Deze voorbeeldaanvraagtekst verwijst naar één brondocument dat in twee doeltalen moet worden vertaald.

Belangrijk

Naast de eerder genoteerde aanvraagparameters moet u ook de aanvraagparameters opnemen"storageType": "File". Anders wordt ervan uitgegaan dat de bron-URL zich op containerniveau bevindt.

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

Alle documenten in een container vertalen met behulp van een aangepaste woordenlijst

Deze voorbeeldaanvraagtekst verwijst naar een broncontainer voor alle documenten die moeten worden vertaald naar een doeltaal met behulp van een woordenlijst.

Zie aanvraagparameters voor meer informatie.

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

Mooi! U hebt zojuist geleerd hoe u een door het systeem toegewezen beheerde identiteit inschakelt en gebruikt. Met een beheerde identiteit voor Azure-resources en Azure RBAChebt u Translator specifieke toegangsrechten verleend voor uw opslagresource zonder SAS-tokens met uw HTTP-aanvragen op te geven.

Volgende stappen

Quickstart: Aan de slag met documentomzetting

Zelfstudie: Toegang tot Azure Storage vanuit een web-app met behulp van beheerde identiteiten