Identità gestite per la traduzione di documenti

  • Articolo

Le identità gestite per le risorse di Azure sono entità servizio che creano un'identità Microsoft Entra e autorizzazioni specifiche per le risorse gestite di Azure. Le identità gestite sono un modo più sicuro per concedere l'accesso ai dati di archiviazione e sostituire il requisito per includere i token di firma di accesso condiviso con gli URL di origine e di destinazione.

Screenshot of managed identity flow (RBAC).

  • È possibile usare le identità gestite per concedere l'accesso a qualsiasi risorsa che supporti l'autenticazione di Microsoft Entra, incluse le proprie applicazioni.

  • Per concedere l'accesso a una risorsa di Azure, assegnare un ruolo di Azure a un'identità gestita usando il Controllo degli accessi in base al ruolo di Azure (Azure RBAC) .

  • Non sono previsti costi aggiuntivi per l'uso di identità gestite in Azure.

Importante

  • Quando si usano identità gestite, non includere un URL del token di firma di accesso condiviso con le richieste HTTP, altrimenti le richieste avranno esito negativo. L'uso di identità gestite sostituisce il requisito per includere token di firma di accesso condiviso (SAS) con gli URL di origine e di destinazione.

  • Per usare le identità gestite per le operazioni di traduzione di documenti, è necessario creare la risorsa Traduttore in un'area geografica specifica di Azure, ad esempio Stati Uniti orientali. Se l'area delle risorse di Traduttore è impostata su Globale, non è possibile usare l'identità gestita per la traduzione dei documenti. È comunque possibile usare token di firma di accesso condiviso (SAS) per la traduzione di documenti.

  • La traduzione dei documenti è disponibile solo nel piano di servizio Standard S1 (con pagamento in base al consumo) o nel piano di sconto volume D3. VederePrezzi dei Servizi di Azure AI - Traduttore.

Prerequisiti

Per iniziare, è necessario:

  • Un account Azure attivo. Se non ne si ha uno, è possibile crearne uno gratuito.

  • Una risorsa Traduttore a servizio singolo (non una risorsa Servizi di Azure AI multiservizio) assegnata a un'area geografica, ad esempio Stati Uniti occidentali. Per i passaggi dettagliati, vedereCreare una risorsa multiservizio.

  • Una breve conoscenza del controllo degli accessi in base al ruolo di Azure (Azure RBAC) tramite il portale di Azure.

  • Un account di archiviazione BLOB di Azure nella stessa area della risorsa Traduttore. È anche necessario creare contenitori per archiviare e organizzare i dati BLOB all'interno dell'account di archiviazione.

  • Se l'account di archiviazione si trova dietro un firewall, è necessario abilitare la configurazione seguente:

    1. Passare al portale di Azure e accedere all'account Azure.

    2. Selezionare l'account di archiviazione.

    3. Nel gruppo Sicurezza e rete nel riquadro sinistro selezionare Rete.

    4. Nella scheda Firewall e reti virtuali selezionare Abilitato da reti virtuali e indirizzi IP selezionati.

      Screenshot: Selected networks radio button selected.

    5. Deselezionare tutte le caselle di controllo.

    6. Assicurarsi che sia selezionato Routing di rete Microsoft.

    7. Nella sezione Istanze di risorse selezionare Microsoft.CognitiveServices/accounts come tipo di risorsa e selezionare la risorsa Traduttore come nome dell'istanza.

    8. Assicurarsi che sia selezionata la casella di controllo Consenti ai servizi di Azure nell'elenco servizi attendibili di accedere a questo account di archiviazione. Per altre informazioni sulla gestione delle eccezioni, vedereConfigurare i firewall e le reti virtuali di Archiviazione di Azure.

      Screenshot: allow trusted services checkbox, portal view.

    9. Seleziona Salva.

      Nota

      La propagazione delle modifiche di rete potrebbe richiedere fino a 5 minuti.

    Anche se l'accesso alla rete è ora consentito, la risorsa Traduttore non è ancora in grado di accedere ai dati nell'account di archiviazione. È necessario creare un'identità gestita e assegnare un ruolo di accesso specifico alla risorsa Traduttore.

Assegnazioni di identità gestite

Ci sono due tipi di identità del servizio gestita: assegnata dal sistema e assegnata dall'utente. Attualmente, la traduzione di documenti supporta l'identità gestita assegnata dal sistema:

  • Un'identità gestita assegnata dal sistema viene abilitata direttamente in un'istanza del servizio. Non è abilitato per impostazione predefinita; è necessario passare alla risorsa e aggiornare l'impostazione di identità.

  • L'identità gestita assegnata dal sistema è associata alla risorsa per tutto il ciclo di vita. Se si elimina la risorsa, viene eliminata anche l'identità gestita.

Nei passaggi seguenti si abiliterà un'identità gestita assegnata dal sistema e si concederà alla risorsa Traduttore l'accesso limitato all'account di archiviazione BLOB di Azure.

Abilitare un'identità gestita assegnata dal sistema

È necessario concedere alla risorsa Traduttore l'accesso all'account di archiviazione prima di poter creare, leggere o eliminare BLOB. Dopo aver abilitato la risorsa Traduttore con un'identità gestita assegnata dal sistema, è possibile usare il controllo degli accessi in base al ruolo di Azure (Azure RBAC) per concedere a Traduttore l'accesso ai contenitori di archiviazione di Azure.

  1. Passare al portale di Azure e accedere all'account Azure.

  2. Selezionare la risorsa Traduttore.

  3. Nel gruppo Gestione risorse nel riquadro sinistro selezionare Identità.

  4. All'interno della scheda Assegnata dal sistema attivare lo Stato.

    Screenshot: resource management identity tab in the Azure portal.

    Importante

    L'identità gestita assegnata dall'utente non soddisfa i requisiti per lo scenario dell'account di archiviazione di trascrizione batch. Assicurarsi di abilitare l'identità gestita assegnata dal sistema.

  5. Seleziona Salva.

Concedere l'accesso all'account di archiviazione per la risorsa Traduttore

Importante

Per assegnare un ruolo di identità gestita assegnata dal sistema, sono necessarie le autorizzazioni Microsoft.Authorization/roleAssignments/write, ad esempio Proprietario o Amministratore accesso utenti, nell'ambito di archiviazione per la risorsa di archiviazione.

  1. Passare al portale di Azure e accedere all'account Azure.

  2. Selezionare la risorsa Traduttore.

  3. Nel gruppo Gestione risorse nel riquadro sinistro selezionare Identità.

  4. In Autorizzazioni selezionare Assegnazioni di ruolo di Azure:

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

  5. Nella pagina Assegnazioni di ruolo di Azure aperta scegliere la sottoscrizione dal menu a discesa e quindi selezionare + Aggiungi assegnazione di ruolo.

    Screenshot: Azure role assignments page in the Azure portal.

  6. Assegnare quindi un ruolo Collaboratore ai dati del BLOB di archiviazione alla risorsa del servizio Traduttore. Il ruolo Collaboratore ai dati dei BLOB di archiviazione fornisce a Traduttore, rappresentato dall'identità gestita assegnata dal sistema, l'accesso in lettura, scrittura ed eliminazione ai dati e al contenitore BLOB. Nella finestra popup Aggiungi assegnazione di ruolo completare i campi come indicato di seguito e selezionare Salva:

    Campo Valore
    Scope Archiviazione.
    Abbonamento La sottoscrizione associata alla risorsa di archiviazione.
    Conto risorse Nome della risorsa di archiviazione.
    Ruolo Collaboratore ai dati del BLOB di archiviazione.

    Screenshot: add role assignments page in the Azure portal.

  7. Dopo che viene visualizzato il messaggio di conferma Assegnazione di ruolo aggiunta, aggiornare la pagina per visualizzarla.

    Screenshot: Added role assignment confirmation pop-up message.

  8. Se non viene visualizzata subito la nuova assegnazione di ruolo, attendere e provare ad aggiornare nuovamente la pagina. Quando si assegnano o si rimuovono le assegnazioni di ruolo, l'applicazione delle modifiche può richiedere fino a 30 minuti.

    Screenshot: Azure role assignments window.

Richieste HTTP

  • Una richiesta di traduzione batch asincrona viene inviata all'endpoint del servizio Traduttore tramite una richiesta POST.

  • Con l'identità gestita e Azure RBAC, non è più necessario includere gli URL di firma di accesso condiviso.

  • In caso di esito positivo, il metodo POST restituisce un codice di risposta 202 Accepted e il servizio crea una richiesta batch.

  • I documenti tradotti vengono visualizzati nel contenitore di destinazione.

Intestazioni

Le intestazioni seguenti sono incluse in ogni richiesta dell'API Traduzione di documenti:

Intestazione HTTP Descrizione
Ocp-Apim-Subscription-Key Obbligatorio: il valore è la chiave di Azure per la risorsa Traduttore o di Servizi di Azure AI.
Content-Type Obbligatorio: specifica il tipo di contenuto del payload. I valori accettati sono application/json o charset=UTF-8.

Corpo della richiesta POST

  • L'URL della richiesta è POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Il corpo della richiesta è un oggetto JSON denominato inputs.
  • L'oggetto inputs contiene sia indirizzi di contenitore sourceURL che targetURL per le coppie di lingue di origine e di destinazione. Con l'identità gestita assegnata dal sistema si usa un URL dell'account di archiviazione normale (nessuna firma di accesso condiviso o altre aggiunte). Il formato è https://<storage_account_name>.blob.core.windows.net/<container_name>.
  • I campi prefix e suffix (facoltativi) vengono usati per filtrare i documenti nel contenitore, incluse le cartelle.
  • Quando il documento viene convertito, viene applicato un valore per il campo glossaries (facoltativo).
  • targetUrl per ogni lingua di destinazione deve essere univoco.

Importante

Se nella destinazione esiste già un file con lo stesso nome, il processo avrà esito negativo. Quando si usano identità gestite, non includere un URL del token di firma di accesso condiviso con le richieste HTTP. In questo caso, le richieste avranno esito negativo.

Tradurre tutti i documenti in un contenitore

Questo corpo della richiesta di esempio fa riferimento a un contenitore di origine per tutti i documenti da tradurre in una lingua di destinazione.

Per altre informazioni, vedereparametri di richiesta.

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

Tradurre un documento specifico in un contenitore

Questo corpo della richiesta di esempio fa riferimento a un singolo documento di origine da tradurre in due lingue di destinazione.

Importante

Oltre ai parametri della richiesta annotati in precedenza, è necessario includere "storageType": "File". In caso contrario, si presuppone che l'URL di origine sia a livello di contenitore.

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

Tradurre tutti i documenti in un contenitore usando un glossario personalizzato

Questo corpo della richiesta di esempio fa riferimento a un contenitore di origine per tutti i documenti da tradurre in una lingua di destinazione usando un glossario.

Per altre informazioni, vedereparametri di richiesta.

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

Ottimo. Si è appena appreso come abilitare e usare un'identità gestita assegnata dal sistema. Con l'identità gestita per le risorse di Azure e Azure RBAC, sono stati concessi a Traduttore diritti di accesso specifici per la risorsa di archiviazione senza includere token di firma di accesso condiviso con le richieste HTTP.

Passaggi successivi

Guida introduttiva: Introduzione alla traduzione di documenti

Esercitazione: Accedere ad Archiviazione di Azure da un'app Web usando identità gestite