Identités managées pour la traduction de documentation

  • Article

Les identités managées pour les ressources Azure sont des principaux de service qui créent une identité Microsoft Entra et des autorisations spécifiques pour les ressources managées Azure. Les identités managées sont un moyen plus sûr d’accorder l’accès aux données de stockage et de remplacer la nécessité d’inclure des jetons de signature d’accès partagé (SAP) avec vos URL source et cible.

Screenshot of managed identity flow (RBAC).

  • Vous pouvez utiliser les identités managées pour octroyer un accès à toute ressource prenant en charge l’authentification Microsoft Entra, y compris vos propres applications.

  • Pour accorder l’accès à une ressource Azure, attribuez un rôle à une identité managée en utilisant le contrôle d’accès en fonction du rôle Azure, le RBAC (Azure RBAC).

  • L’utilisation d’identités managées dans Azure n’occasionne aucun coût supplémentaire.

Important

  • Lorsque vous utilisez des identités managées, n’incluez pas d’URL de jeton SAS avec vos requêtes HTTP, sinon vos requêtes échouent. L’utilisation d’identités managées remplace la nécessité d’inclure des jetons de signature d’accès partagé (SAP) avec vos URL source et cible.

  • Pour utiliser des identités managées pour les opérations de traduction de documentation, vous devez créer votre ressource Translator dans une région Azure géographique spécifique, comme USA Est. Si votre région de ressources Translator est définie sur Global, vous ne pouvez pas utiliser l’identité managée pour la traduction de documentation. Vous pouvez toujours utiliser des jetons de signature d’accès partagé (SAS) pour la traduction de documentation.

  • La Traduction de documentation est disponible uniquement dans le plan de service Standard S1 (paiement à l’utilisation) ou dans le plan de remise sur la quantité D3. ConsultezTarification Azure AI services – Translator.

Prérequis

Pour commencer, vous avez besoin des éléments suivants :

  • Un compte Azure actif : si vous n’en avez pas, vous pouvez créer un compte gratuit.

  • Une ressource Traducteur mono-service (non une ressource Azure AI services multiservice) attribuée à une région géographique telle que USA Ouest. Pour obtenir des instructions détaillées, consultezCréer une ressource multiservices.

  • Connaissances générales sur le contrôle d’accès en fonction du rôle Azure (Azure RBAC) à l’aide du portail Azure.

  • Un compte de stockage Blob Azure dans la même région que votre ressource Traducteur. Vous devez aussi créer des conteneurs pour stocker et organiser vos données d’objet blob dans votre compte de stockage.

  • Si votre compte de stockage se trouve derrière un pare-feu, vous devez activer la configuration suivante :

    1. Accédez au portail Azure et connectez-vous à votre compte Azure.

    2. Sélectionnez le compte Stockage.

    3. Dans le groupe Sécurité + réseau dans le volet gauche, sélectionnez Réseau.

    4. Sous l’onglet Pare-feu et réseaux virtuels, sélectionnez Activé à partir des réseaux virtuels et adresses IP sélectionnés.

      Screenshot: Selected networks radio button selected.

    5. Décochez toutes les cases.

    6. Vérifiez que Routage réseau Microsoft est sélectionné.

    7. Dans la section Instances de ressources, sélectionnez le type de ressource Microsoft.CognitiveServices/accounts, puis sélectionnez votre ressource Traducteur comme nom d’instance.

    8. Assurez-vous que la case Autoriser les services Azure dans la liste des services approuvés à accéder à ce compte de stockage est activée. Pour plus d’informations sur la gestion des exceptions, consultez l’article Configurer des pare-feux et des réseaux virtuels dans Stockage Azure.

      Screenshot: allow trusted services checkbox, portal view.

    9. Sélectionnez Enregistrer.

      Notes

      La propagation des modifications réseau peut prendre jusqu’à 5 minutes.

    Votre ressource Translator ne peut toujours pas accéder aux données de votre compte de stockage, même avec un accès réseau désormais autorisé. Vous devez créer une identité managée pour, tout comme attribuer un rôle d’accès spécifique à votre ressource Translator.

Attributions d’identités managées

Il existe deux types d’identités managées : celles qui sont affectées par le système et celles qui sont affectées par l’utilisateur. Actuellement, la traduction de documentation prend en charge les identités managées affectées par le système :

  • Une identité managée affectée par le système est activée directement sur une instance de service. Elle n’est pas activée par défaut. Vous devez accéder à votre ressource et mettre à jour le paramètre d’identité.

  • L’identité managée affectée par le système est liée à votre ressource tout au long de son cycle de vie. Si vous supprimez votre ressource, l’identité managée est également supprimée.

Dans les étapes suivantes, nous activons une identité managée affectée par le système et accordons à votre ressource Traducteur un accès limité à votre compte de stockage Blob Azure.

Activer une identité managée affectée par le système

Vous devez accorder à la ressource Traducteur l’accès à votre compte de stockage avant de pouvoir créer, lire ou supprimer des objets blob. Une fois que vous avez activé la ressource Traducteur avec une identité managée affectée par le système, vous pouvez utiliser le contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour accorder à Traducteur l’accès à vos conteneurs de stockage Azure.

  1. Accédez au portail Azure et connectez-vous à votre compte Azure.

  2. Sélectionnez la ressource Traducteur.

  3. Dans le groupe Gestion des ressources dans le volet gauche, sélectionnez Identité.

  4. Dans l’onglet Affecté par le système, activez le bouton bascule État.

    Screenshot: resource management identity tab in the Azure portal.

    Important

    L’identité managée affectée par l’utilisateur ne répond pas aux exigences du scénario de compte de stockage de transcription par lots. Veillez à activer l’identité managée affectée par le système.

  5. Sélectionnez Enregistrer.

Accorder l’accès au compte de stockage pour votre ressource Traducteur

Important

Pour attribuer un rôle d’identité managée affectée par le système, vous avez besoin d’autorisations Microsoft.Authorization/roleAssignments/write, telles que Propriétaire ou Administrateur de l’accès utilisateur dans l’étendue de stockage de la ressource de stockage.

  1. Accédez au portail Azure et connectez-vous à votre compte Azure.

  2. Sélectionnez la ressource Traducteur.

  3. Dans le groupe Gestion des ressources dans le volet gauche, sélectionnez Identité.

  4. Sous Autorisations, sélectionnez Attributions des rôles Azure :

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

  5. Dans la page Attributions de rôles Azure qui s’est ouverte, choisissez votre abonnement dans le menu déroulant, puis sélectionnez + Ajouter une attribution de rôle.

    Screenshot: Azure role assignments page in the Azure portal.

  6. Vous devez ensuite attribuer un rôle Contributeur aux données Blob du stockage à votre ressource de service Translator. Le rôle Contributeur aux données Blob du stockage accorde à Traducteur (représenté par l’identité managée affectée par le système) un accès en lecture, écriture et suppression au conteneur d’objets blob et aux données. Dans la fenêtre contextuelle Ajouter une attribution de rôle, renseignez les champs comme suit et sélectionnez Enregistrer :

    Champ Valeur
    Étendue Stockage.
    Abonnement L’abonnement associé à votre ressource de stockage.
    Ressource Le nom de votre ressource de stockage.
    Rôle Contributeur aux données Blob du stockage.

    Screenshot: add role assignments page in the Azure portal.

  7. Une fois que le message de confirmation Attribution de rôle ajoutée s’affiche, actualisez la page pour voir l’attribution de rôle ajoutée.

    Screenshot: Added role assignment confirmation pop-up message.

  8. Si vous ne voyez pas immédiatement la nouvelle attribution de rôle, patientez et essayez d’actualiser la page une nouvelle fois. Lorsque vous attribuez des rôles ou supprimez des attributions de rôle, un délai maximal de 30 minutes peut être nécessaire avant que les modifications prennent effet.

    Screenshot: Azure role assignments window.

Des requêtes HTTP

  • Une requête de traduction par lots asynchrone est envoyée à votre point de terminaison de service Translator via une requête POST.

  • Avec une identité managée et Azure RBAC, vous n’avez plus besoin d’inclure d’URL SAS.

  • En cas de réussite, la méthode POST retourne un code de réponse 202 Accepted et le service crée une demande de lot.

  • Les documents traduits s’affichent dans votre conteneur cible.

En-têtes

Les en-têtes suivants sont inclus avec chaque requête d’API Traduction de documentation :

En-tête HTTP Description
Ocp-Apim-Subscription-Key Obligatoire : La valeur est la clé Azure de votre ressource Translator ou Azure AI services.
Content-Type Obligatoire : spécifie le type de contenu de la charge utile. Les valeurs acceptées sont application/json ou charset=UTF-8.

Corps de requête POST

  • L’URL de la demande est POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Le corps de la requête est un objet JSON nommé inputs.
  • L’objet inputs contient à la fois les adresses de conteneur sourceURL et targetURL pour vos paires de langue source et cible. Avec une identité managée affectée par le système, vous utilisez une URL de compte de stockage brute (sans signature d’accès partagé ou autre ajout). Le format est https://<storage_account_name>.blob.core.windows.net/<container_name>.
  • Les champs prefix et suffix (facultatifs) sont utilisés pour filtrer les documents présents dans le conteneur, dont les dossiers.
  • Une valeur du champ glossaries (facultatif) est appliquée quand le document est en cours de traduction.
  • La valeur targetUrl de chaque langue cible doit être unique.

Important

Si un fichier portant le même nom existe déjà dans la destination, le travail se solde par un échec. Lorsque vous utilisez des identités managées, n’incluez pas d’URL de jeton SAS avec vos requêtes HTTP. Si vous procédez ainsi, vos demandes échouent.

Traduire tous les documents dans un conteneur

Cet exemple de corps de demande fait référence à un conteneur source pour tous les documents à traduire dans une langue cible.

Pour plus d’informations, consultez les paramètres de demande.

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

Traduire un document spécifique dans un conteneur

Cet exemple de corps de demande fait référence à un document source unique à traduire dans deux langues cibles.

Important

En plus des paramètres de demande indiqués précédemment, vous devez inclure "storageType": "File". À défaut, l’URL source est supposée être au niveau du conteneur.

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

Traduire tous les documents d’un conteneur à l’aide d’un glossaire personnalisé

Cet exemple de corps de demande fait référence à un conteneur source pour tous les documents à traduire dans une langue cible à l’aide d’un glossaire.

Pour plus d’informations, consultez les paramètres de demande.

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

Très bien ! Vous venez d’apprendre à activer et utiliser une identité managée affectée par le système. Avec une identité managée pour les ressources Azure et Azure RBAC, vous avez accordé à Translator des droits d’accès spécifiques à votre ressource de stockage sans inclure de jetons SAS avec vos requêtes HTTP.

Étapes suivantes

Démarrage rapide : Bien démarrer avec la traduction de documents

Tutoriel : Accéder à Stockage Azure à partir d’une application web à l’aide d’identités managées