Identités managées pour la traduction de documentation

Important

  • Actuellement, la traduction de documentation ne prend pas en charge l’identité managée dans la région globale. Si vous comptez utiliser des identités managées pour des opérations de traduction de documentation, créez votre ressource Traducteur dans une région Azure non globale.

  • 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. VoirTarification de Cognitive Services - Traducteur.

Les identités managées pour les ressources Azure sont des principaux de service qui créent une identité Azure AD (Azure Active Directory) et des autorisations spécifiques pour des ressources managées Azure :

  • Vous pouvez utiliser des identités managées pour accorder l’accès à toute ressource qui prend en charge l’authentification Azure AD, y compris vos propres applications. Avec les identités managées, vous n’avez plus besoin d’inclure des jetons de signature d’accès partagé (SAS) avec vos requêtes HTTP.

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

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

Conseil

  • 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.

  • Les identités managées constituent un moyen plus sûr d’accorder l’accès aux données sans avoir à inclure de jetons SAS dans vos requêtes HTTP.

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

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 allons activer une identité managée affectée par le système et accorder à votre ressource Traducteur un accès limité à votre compte de stockage Blob Azure.

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

Important

Pour activer une 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. Vous pouvez spécifier une étendue à quatre niveaux : groupe d’administration, abonnement, groupe de ressources ou ressource.

  1. Connectez-vous au portail Azure à l’aide d’un compte associé à votre abonnement Azure.

  2. Accédez à la page de votre ressource Translator dans le portail Azure.

  3. Dans le rail de gauche, sélectionnez Identité dans la liste Gestion des ressources :

    Capture d’écran : onglet identité de gestion des ressources dans le portail Azure.

  4. Dans la fenêtre principale, basculez le curseur État affecté par le système sur Activé.

Accorder l’accès à votre compte de stockage

Vous devez accorder à 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é Translator 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 à Translator l’accès à vos conteneurs de stockage Azure.

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.

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

    Capture d’écran : activer une identité managée affectée par le système dans le portail Azure

  2. Une page des attributions de rôles Azure s’ouvre. Choisissez votre abonnement dans le menu déroulant, puis sélectionnez + Ajouter une attribution de rôle.

    Capture d’écran : page des attributions de rôles Azure dans le portail Azure

    Notes

    Si vous ne parvenez pas à attribuer un rôle dans le portail Azure parce que l’option Ajouter > Ajouter une attribution de rôle est désactivée ou que vous recevez l’erreur d’autorisation « Vous ne disposez pas des autorisations nécessaires pour ajouter une attribution de rôle à cette étendue », vérifiez que vous êtes actuellement connecté en tant qu’utilisateur avec un rôle attribué qui dispose des autorisations Microsoft.Authorization/roleAssignments/write, comme Propriétaire ou Administrateur de l’accès utilisateur dans l’étendue de stockage de la ressource de stockage.

  3. Ensuite, vous allez attribuer un rôle Contributeur aux données Blob du stockage à votre ressource de service Traducteur. 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.

    Capture d’écran : page d’ajout d’attributions de rôles dans le portail Azure.

  4. Une fois que vous avez reçu le message de confirmation Attribution de rôle ajoutée, actualisez la page pour voir l’attribution de rôle ajoutée.

    Capture d’écran : message contextuel de confirmation de l’ajout de l’attribution de rôle

  5. Si vous ne voyez pas immédiatement la modification, 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.

    Capture d’écran : fenêtre des attributions de rôles Azure.

Des requêtes HTTP

  • Une demande de Traduction de documentation par lot est soumise à votre point de terminaison de service Translator par le biais d’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 la demande de lot est créée par le service.

  • 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 Cognitive 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 requête est POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/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

  • 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.

Notes

Si un fichier portant le même nom existe déjà dans la destination, le travail se solde par un échec.

Traduire tous les documents dans un conteneur

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr"
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduire un document spécifique dans un conteneur

  • Obligatoire : "storageType": "File"
  • Cet exemple de demande retourne un seul document traduit en deux langues cibles :
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-es/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-de/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

Traduire des documents à l’aide d’un glossaire personnalisé

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.windows.net/source",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.windows.net/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Très bien ! Vous avez appris à 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

Didacticiel