Partager via

Fonctionnalités de l’API REST pour les pipelines de données dans Fabric Data Factory

Fabric Data Factory fournit un ensemble robuste d’API qui permettent aux utilisateurs d’automatiser et de gérer efficacement leurs pipelines de données. Ces API permettent une intégration transparente avec différentes sources de données et services, ce qui permet aux utilisateurs de créer, mettre à jour et surveiller leurs flux de travail de données de manière programmatique. Les API prennent en charge un large éventail d’opérations, notamment la création, la lecture, la mise à jour et la suppression (CRUD) de pipeline, la planification et la surveillance. Cela permet aux utilisateurs de gérer plus facilement leurs processus d’intégration des données.

Cas d’utilisation d’API pour les pipelines de données

Les API pour les pipelines dans Fabric Data Factory peuvent être utilisées dans différents scénarios :

  • Déploiement automatisé : automatisez le déploiement de pipelines de données dans différents environnements (développement, test, production) à l’aide des pratiques CI/CD.
  • Surveillance et alertes : configurez des systèmes de surveillance et d’alerte automatisés pour suivre l’état des pipelines de données et recevoir des notifications si des défaillances ou des problèmes de performances se produisent.
  • Intégration des données : intégrez des données de plusieurs sources, telles que des bases de données, des lacs de données et des services cloud, dans un pipeline de données unifié pour le traitement et l’analyse.
  • Gestion des erreurs : implémentez des mécanismes personnalisés de gestion des erreurs et de nouvelle tentative pour garantir que les pipelines de données s’exécutent en douceur et récupèrent des défaillances.

Présentation des API

Pour utiliser efficacement les API pour les pipelines dans Fabric Data Factory, il est essentiel de comprendre les concepts et composants clés :

  • Points de terminaison : les points de terminaison d’API fournissent l’accès à différentes opérations de pipeline, telles que la création, la mise à jour et la suppression de pipelines.
  • Authentification : sécurisez l’accès aux API à l’aide de mécanismes d’authentification tels que les clés OAuth ou API.
  • Requêtes et réponses : il est important comprendre la structure des requêtes et réponses d’API, y compris les paramètres requis et la sortie attendue.
  • Limites de débit : tenez compte des limites de débit imposées à l’utilisation de l’API pour éviter de dépasser le nombre autorisé de requêtes.

Prise en charge CRUD

CRUD signifie Créer, Lire, Mettre à jour et Supprimer, qui sont les quatre opérations de base qui peuvent être effectuées sur les données. Dans Fabric Data Factory, les opérations CRUD sont prises en charge via l’API Fabric pour Data Factory. Ces API permettent aux utilisateurs de gérer leurs pipelines de manière programmatique. Voici quelques points clés sur la prise en charge CRUD :

  • Créer : créez des pipelines à l’aide de l’API. Il s’agit de définir la structure du pipeline, de spécifier les sources de données, les transformations et les destinations.
  • Lire : récupérez des informations sur les pipelines existants. Il s’agit notamment des détails concernant leur configuration, leur état et l’historique de leur exécution.
  • Mette à jour : mettez à jour les pipelines existants. Il peut s’agir de modifier la structure du pipeline, de changer les sources de données ou de mettre à jour la logique de transformation.
  • Supprimer : supprimez les pipelines qui ne sont plus nécessaires. Cela permet de gérer et de nettoyer les ressources.

La principale documentation de référence en ligne pour les API REST de Microsoft Fabric se trouve dans Documentation API REST Microsoft Fabric.

Prise en main des API REST pour les pipelines de données

Les exemples suivants montrent comment créer, mettre à jour et gérer des pipelines à l’aide des API Fabric Data Factory.

Obtenir un jeton d’autorisation

Avant d’utiliser les autres API REST, vous devez disposer du jeton du porteur.

Important

Dans les exemples suivants, assurez-vous que le mot « Porteur » (avec un espace) précède le jeton d’accès lui-même. Lorsque vous utilisez un client d’API et sélectionnez « Jeton du porteur » comme type d’authentification, « Porteur » est automatiquement inséré pour vous et nécessite uniquement que le jeton d’accès soit fourni.

Option 1 : Utilisation de MSAL.Net

Reportez-vous à la section Obtenir un jeton du guide de démarrage rapide de l’API Fabric pour savoir comment obtenir un jeton d’autorisation MSAL.

Utilisez MSAL.Net pour acquérir un jeton Microsoft Entra ID pour le service Fabric avec les étendues suivantes : Workspace.ReadWrite.All, Item.ReadWrite.All. Pour plus d’informations sur l’acquisition de jetons avec MSAL.Net, consultez Acquisition de jetons – Bibliothèque d’authentification Microsoft pour .NET.

Copiez le jeton à partir de la propriété AccessToken et remplacez l’espace réservé du <jeton d’accès > dans les exemples suivants par le jeton.

Option 2 : utiliser le portail Fabric

Connectez-vous au portail Fabric pour le locataire sur lequel vous souhaitez effectuer un test, puis appuyez sur F12 pour accéder au mode développeur du navigateur. Dans la console, exécutez :

powerBIAccessToken

Copiez le jeton et remplacez l’espace réservé <AccessToken> dans les exemples suivants par le jeton.

Créer un pipeline

Créez un pipeline dans un espace de travail spécifié.

Exemple de requête :

URI : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items

En-têtes :

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Charge utile :

{
  "displayName": "My pipeline",
  "description": "My pipeline description",
  "type": "pipeline"
}

Exemple de réponse :

{
    "id": "<artifactId>",
    "type": "pipeline",
    "displayName": "My pipeline",
    "description": "My pipeline description",
    "workspaceId": "<workspaceId>"
}

Créer un pipeline avec une définition

Créez un pipeline avec une définition base64 dans un espace de travail spécifié.

Exemple de requête :

URI : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items

En-têtes :

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Charge utile :

{
  "displayName": " My pipeline",
  "description": "My pipeline description",

  "type": "pipeline",
  "definition": { 
    "parts": [ 
      { 
        "path": "pipeline-content.json", 
        "payload": "<Your Base64 encoded JSON payload>"
        "payloadType": "InlineBase64" 
      } 
    ] 
  }
}

Exemple de réponse :

{
    "id": "<Your artifactId>",
    "type": "pipeline",
    "displayName": "My pipeline",
    "description": "My pipeline description",
    "workspaceId": "<Your workspaceId>"
}

Obtenir le pipeline

Retourne les propriétés du pipeline spécifié.

Exemple de requête :

URI : GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

En-têtes :

{
  "Authorization": "Bearer <access-token>"
}

Exemple de réponse :

{
    "id": "<Your artifactId>",
    "type": "pipeline",
    "displayName": "My pipeline",
    "description": "My pipeline description",
    "workspaceId": "<Your workspaceId>"
}

Obtenir le pipeline avec la définition

Retourne la définition de l’élément de pipeline.

Exemple de requête :

URI : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/getDefinition

En-têtes :

{
  "Authorization": "Bearer <access-token>"
}

Exemple de réponse :

{
    "definition": {
        "parts": [
            {
                "path": "pipeline-content.json",
                "payload": "<Base64 encoded payload>"
                "payloadType": "InlineBase64"
            },
            {
                "path": ".platform",
                "payload": "<Base64 encoded payload>",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

Mettre à jour le flux de travail

Met à jour les propriétés du pipeline.

Exemple de requête :

URI : PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

En-têtes :

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Charge utile :

{
  "displayName": "My pipeline updated",
  "description": "My pipeline description updated",
  "type": "pipeline"
}

Exemple de réponse :

{
    "id": "<Your artifactId>",
    "type": "pipeline",
    "displayName": "My pipeline updated",
    "description": "My pipeline description updated",
    "workspaceId": "<Your workspaceId>"
}

Mettre à jour le pipeline avec la définition

Met à jour la définition de l’élément de pipeline.

Exemple de requête :

URI : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/updateDefinition

En-têtes :

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Charge utile :

{
  "displayName": " My pipeline ",
  "type": "pipeline",
  "definition": {
    "parts": [ 
      { 
        "path": "pipeline-content.json", 
        "payload": "<Your Base64 encoded payload>", 
        "payloadType": "InlineBase64" 
      }
    ]
  }
}

Exemple de réponse :

200 OK

Supprimer le pipeline

Supprime le pipeline spécifié.

Exemple de requête :

URI : DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

En-têtes :

{
  "Authorization": "Bearer <access-token>"
}

Exemple de réponse :

200 OK

Exécuter le travail de pipeline à la demande

Exécute une instance de travail de pipeline à la demande.

Exemple de requête :

URI : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/jobs/instances?jobType=Refresh

En-têtes :

{
  "Authorization": "Bearer <access-token>"
}

Charge utile :

{
    "executionData": {
        "pipelineName": "pipeline",
        "OwnerUserPrincipalName": "<user@domain.com>",
        "OwnerUserObjectId": "<Your ObjectId>"
    }
}

Exemple de réponse :

202 Accepted

Obtenir une instance de travail de pipeline

Obtient l’instance de travail du pipeline singulier.

Exemple de requête :

URI : GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/jobs/instances/{jobInstanceId}

En-têtes :

{
  "Authorization": "Bearer <access-token>"
}

Exemple de réponse :

{
  "id": "<id>",
  "itemId": "<itemId>",
  "jobType": "Refresh",
  "invokeType": "Manual",
  "status": "Completed",
  "rootActivityId": "<rootActivityId>",
  "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "failureReason": null
}

Annuler l’instance de travail de pipeline

Annule l’instance de travail d’un pipeline.

Exemple de requête :

URI : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/jobs/instances/{jobInstanceId}/cancel

En-têtes :

{
  "Authorization": "Bearer <access-token>"
}

Exemple de réponse :

* Emplacement : https://api.fabric.microsoft.com/v1/workspaces/<worksapceId>/items/<itemId>/jobs/instances/<jobInstanceId>Réessayer après : 60

Interroger les exécutions d’activité

Exemple:

POST https://api.fabric.microsoft.com/v1/workspaces/<your WS Id>/datapipelines/pipelineruns/<job id>/queryactivityruns

Corps:

{
  "filters":[],
  "orderBy":[{"orderBy":"ActivityRunStart","order":"DESC"}],
  "lastUpdatedAfter":"2024-05-22T14:02:04.1423888Z",
  "lastUpdatedBefore":"2024-05-24T13:21:27.738Z"
}

Remarque

« ID de travail » est le même ID créé et utilisé dans les API publiques du planificateur de travaux

Réponse 200 :

[
    {
        "pipelineName": "ca91f97e-5bdd-4fe1-b39a-1f134f26a701",
        "pipelineRunId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
        "activityName": "Wait1",
        "activityType": "Wait",
        "activityRunId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "linkedServiceName": "",
        "status": "Succeeded",
        "activityRunStart": "2024-05-23T13:43:03.6397566Z",
        "activityRunEnd": "2024-05-23T13:43:31.3906179Z",
        "durationInMs": 27750,
        "input": {
            "waitTimeInSeconds": 27
        },
        "output": {},
        "error": {
            "errorCode": "",
            "message": "",
            "failureType": "",
            "target": "Wait1",
            "details": ""
        },
        "retryAttempt": null,
        "iterationHash": "",
        "userProperties": {},
        "recoveryStatus": "None",
        "integrationRuntimeNames": null,
        "executionDetails": null,
        "id": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/PROVIDERS/MICROSOFT.TRIDENT/WORKSPACES/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/pipelineruns/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/activityruns/cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a"
    }
]

Prise en charge du nom de principal du service (SPN)

Le nom du principal de service (SPN) est une fonctionnalité d’identité de sécurité utilisée par les applications ou les services pour accéder à des ressources spécifiques. Dans Fabric Data Factory, la prise en charge du SPN est essentielle pour permettre un accès sécurisé et automatisé aux sources de données. Voici quelques points clés sur la prise en charge du SPN :

  • Authentification : les SPN sont utilisés pour authentifier des applications ou des services lors de l’accès à des sources de données. Cela garantit que seules les entités autorisées peuvent accéder aux données.
  • Configuration : pour utiliser des SPN, vous devez créer un Principal de Service dans Azure et lui accorder les autorisations nécessaires pour accéder à la source de données. Par exemple, si vous utilisez un lac de données, le principal de service a besoin d’un accès en lecture aux données blob de stockage.
  • connexion : lors de la configuration d’une connexion de données dans Fabric Data Factory, vous pouvez choisir de vous authentifier à l’aide d’un principal de service. Cela implique de fournir l’ID de locataire, l’ID client et la clé secrète client du principal de service.
  • Sécurité : l’utilisation des SPN améliore la sécurité en évitant l’emploi d’identifiants codés en dur dans vos flux de données. Il permet également une meilleure gestion des autorisations d’accès et de l’audit des activités d’accès.

Pour plus d'informations pour la configuration et l'utilisation des SPN dans Fabric Data Factory, reportez-vous à Prise en charge des SPN dans Data Factory.

Limites actuelles

  • Limitation du travail : les API d’exécution sont invocables, mais l’exécution actuelle ne réussit jamais (comme l’exécution/l’actualisation à partir de l’interface utilisateur).
  • Éléments non Power BI Fabric : l’espace de travail doit se trouver sur une capacité Fabric de prise en charge.
  • Création d’un élément : utilisez creationPayload ou la définition, mais n’utilisez pas les deux en même temps.

Contenu connexe

Pour plus d’informations sur les API REST pour les pipelines de données dans Fabric Data Factory, consultez le contenu suivant :

Documentation

Tutoriels