Tutoriel : Utiliser les API REST

Article
08/23/2023

Dans ce tutoriel, vous allez apprendre à utiliser les API REST du plan de données Microsoft Purview. Toute personne souhaitant envoyer des données à Microsoft Purview, inclure Microsoft Purview dans le cadre d’un processus automatisé ou créer sa propre expérience utilisateur sur Microsoft Purview peut utiliser les API REST pour le faire.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Configuration requise

Pour commencer, vous devez disposer d’un compte Microsoft Purview existant. Si vous n’avez pas de catalogue, consultez le guide de démarrage rapide pour créer un compte Microsoft Purview.

Créer un principal de service (application)

Pour qu’un client d’API REST accède aux API du plan de données Microsoft Purview, le client doit disposer d’un principal de service (application) et d’une identité que Microsoft Purview reconnaît et qui est configurée pour approuver. Lorsque vous effectuez des appels d’API REST, l’identité de ce principal de service est utilisée pour l’autorisation.

Les clients qui ont utilisé des principaux de service existants (ID d’application) ont connu un taux élevé de défaillances. Par conséquent, nous vous recommandons de créer un principal de service pour appeler des API.

Pour créer un principal de service :

Connectez-vous au Portail Azure.
Dans le portail, recherchez et sélectionnez Azure Active Directory.
Dans la page Azure Active Directory, sélectionnez inscriptions d'applications dans le volet gauche.
Sélectionnez Nouvelle inscription.
Dans la page Inscrire une application :
1. Entrez un Nom pour l’application (le nom du principal de service).
2. Sélectionnez Comptes dans cet annuaire organisationnel uniquement (<nom> de votre locataire uniquement - Locataire unique).
3. Pour URI de redirection (facultatif), sélectionnez Web et entrez une valeur. Cette valeur n’a pas besoin d’être un point de terminaison valide. https://exampleURI.com Je vais le faire.
4. Sélectionner Inscription.
Dans la page nouveau principal de service, copiez les valeurs du Nom d’affichage et de l’ID d’application (client) à enregistrer ultérieurement.

L’ID d’application est la client_id valeur de l’exemple de code.

Pour utiliser le principal de service (application), vous devez connaître le mot de passe du principal de service qui peut être trouvé par :

Dans le Portail Azure, recherchez et sélectionnez Azure Active Directory, puis sélectionnez inscriptions d'applications dans le volet gauche.
Sélectionnez votre principal de service (application) dans la liste.
Sélectionnez Certificats & secrets dans le volet gauche.
Sélectionnez Nouvelle clé secrète client.
Dans la page Ajouter une clé secrète client , entrez une Description, sélectionnez un délai d’expiration sous Expire, puis sélectionnez Ajouter.

Dans la page Secrets client , la chaîne dans la colonne Valeur de votre nouveau secret est votre mot de passe. Enregistrez cette valeur.

Configurer l’authentification à l’aide du principal de service

Une fois le principal de service créé, vous devez attribuer les rôles de plan de données de votre compte Purview au principal de service créé ci-dessus. Suivez les étapes ci-dessous pour attribuer le rôle approprié afin d’établir l’approbation entre le principal de service et le compte Purview :

Accédez à votre portail de gouvernance Microsoft Purview.
Sélectionnez Data Map dans le menu de gauche.
Sélectionnez Collections.
Sélectionnez la collection racine dans le menu collections. Il s’agit de la première collection de la liste et aura le même nom que votre compte Microsoft Purview.

Remarque

Vous pouvez également attribuer l’autorisation de principal de service à n’importe quelle sous-collection, au lieu de la collection racine. Toutefois, toutes les API seront limitées à cette collection (et aux sous-collections qui héritent des autorisations), et les utilisateurs qui tentent d’appeler l’API pour une autre collection recevront des erreurs.
Sélectionnez l’onglet Attributions de rôles .
Attribuez les rôles suivants au principal de service créé précédemment pour accéder à différents plans de données dans Microsoft Purview. Pour obtenir des instructions détaillées, consultez Attribuer des rôles Azure à l’aide du portail de gouvernance Microsoft Purview.
- Rôle conservateur de données pour accéder au plan de données du catalogue.
- Rôle Administrateur de source de données pour accéder à l’analyse du plan de données.
- Collection Administration rôle pour accéder au plan de données du compte et au plan de données de la stratégie de métadonnées.
- Rôle d’auteur de stratégie pour accéder à l’API de stratégies DevOps
Remarque

Seuls les membres du rôle de Administration de collecte peuvent attribuer des rôles de plan de données dans Microsoft Purview. Pour plus d’informations sur les rôles Microsoft Purview, consultez Access Control dans Microsoft Purview.

Obtenir un jeton

Vous pouvez envoyer une requête POST à l’URL suivante pour obtenir un jeton d’accès.

https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

Vous pouvez trouver votre ID de locataire en recherchant Propriétés du locataire dans le Portail Azure. L’ID sera disponible sur la page des propriétés du locataire.

Les paramètres suivants doivent être passés à l’URL ci-dessus :

client_id : ID client de l’application inscrite dans Azure Active Directory et affectée à un rôle de plan de données pour le compte Microsoft Purview.
client_secret : clé secrète client créée pour l’application ci-dessus.
grant_type : il doit s’agir de « client_credentials ».
ressource : 'https://purview.azure.net'

Voici un exemple de requête POST dans PowerShell :

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }

Invoke-WebRequest $url -Method Post -Body $params -UseBasicParsing | ConvertFrom-Json

Exemple de jeton de réponse :

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }

Conseil

Si vous recevez un message d’erreur indiquant : L’échange de jetons cross-origin est autorisé uniquement pour le type client « Application monopage ».

Vérifiez vos en-têtes de requête et vérifiez que votre demande ne contient pas l’en-tête « origin ».
Vérifiez que votre URI de redirection est défini sur web dans votre principal de service.
Si vous utilisez une application comme Postman, assurez-vous que votre logiciel est à jour.

Utilisez le jeton d’accès ci-dessus pour appeler les API du plan de données.

Prochaines étapes

Gérer les API REST du plan de données Microsoft Purview de sources de données

Partager via