Funcionalidades de api REST para canalizaciones de datos en Fabric Data Factory

2025-04-30

Fabric Data Factory proporciona un conjunto sólido de API que permiten a los usuarios automatizar y administrar sus canalizaciones de datos de forma eficaz. Estas API permiten una integración perfecta con varios orígenes de datos y servicios, lo que permite a los usuarios crear, actualizar y supervisar sus flujos de trabajo de datos mediante programación. Las API admiten una amplia gama de operaciones, como CRUD de canalización (Crear, leer, actualizar y eliminar), programar y supervisar. Esto facilita a los usuarios la administración de sus procesos de integración de datos.

Casos de uso de API para canalizaciones de datos

Las API para canalizaciones de Fabric Data Factory se pueden usar en varios escenarios:

Implementación automatizada: automatiza la implementación de canalizaciones de datos en distintos entornos (desarrollo, pruebas, producción) mediante prácticas de CI/CD.
Supervisión y alertas: configura sistemas de supervisión y alertas automatizados para realizar un seguimiento del estado de las canalizaciones de datos y recibir notificaciones si se producen errores o problemas de rendimiento.
Integración de datos: integra datos de varios orígenes, como bases de datos, lagos de datos y servicios en la nube, en una canalización de datos unificada para el procesamiento y el análisis.
Control de errores: implementa mecanismos personalizados de control de errores y reintento para garantizar que las canalizaciones de datos se ejecuten sin problemas y se recuperen de los errores.

Descripción de las API

A fin de usar eficazmente las API para canalizaciones en Fabric Data Factory, es esencial comprender los conceptos y componentes clave:

Puntos de conexión: los puntos de conexión de API proporcionan acceso a varias operaciones de canalización, como crear, actualizar y eliminar canalizaciones.
Autenticación: protege el acceso a las API mediante mecanismos de autenticación como OAuth o claves de API.
Solicitudes y respuestas: comprende la estructura de las solicitudes y respuestas de API, incluidos los parámetros necesarios y la salida esperada.
Límites de frecuencia: ten en cuenta los límites de frecuencia impuestos en el uso de las API para evitar superar el número permitido de solicitudes.

Compatibilidad con CRUD

CRUD significa Crear, Leer, Actualizar y Eliminar, que son las cuatro operaciones básicas que se pueden realizar en los datos. En Fabric Data Factory, las operaciones CRUD se admiten mediante la API de Fabric para Data Factory. Estas API permiten a los usuarios administrar sus canalizaciones mediante programación. Estos son algunos puntos clave sobre la compatibilidad con CRUD:

Crear: crea canalizaciones mediante la API. Esto implica definir la estructura de canalización, especificar orígenes de datos, transformaciones y destinos.
Leer: recupera información sobre las canalizaciones existentes. Esto incluye detalles sobre su configuración, estado e historial de ejecución.
Actualizar: actualiza las canalizaciones existentes. Esto puede implicar la modificación de la estructura de canalización, el cambio de orígenes de datos o la actualización de la lógica de transformación.
Eliminar: elimina canalizaciones que ya no sean necesarias. Esto ayuda a administrar y limpiar los recursos.

La documentación de referencia en línea principal de las API REST de Microsoft Fabric se puede encontrar en la documentación de la API REST de Microsoft Fabric.

Introducción a las API REST para canalizaciones de datos

En los ejemplos siguientes se muestra cómo crear, actualizar y administrar canalizaciones mediante las API de Fabric Data Factory.

Obtenga un token de autorización

Antes de usar las otras API REST, debes tener el token de portador.

Importante

En los ejemplos siguientes, asegúrese de que la palabra "Bearer" (con un espacio) precede al propio token de acceso. Cuando se usa un cliente de API y se selecciona "Token Bearer" como tipo de autenticación, "Bearer " se inserta automáticamente y solo se requiere que se proporcione el token de acceso.

Opción 1: Uso de MSAL.Net

Consulte la sección Obtención de token del inicio rápido de la API Fabric como ejemplo de cómo obtener el token de autorización de MSAL.

Usa MSAL.Net a fin de adquirir un token de Microsoft Entra ID para el servicio Fabric con los siguientes ámbitos: Workspace.ReadWrite.All, Item.ReadWrite.All. Para obtener más información sobre la adquisición de tokens con MSAL.Net, consulte Adquisición de tokens: Biblioteca de autenticación de Microsoft para .NET.

Copie el token de la propiedad AccessToken y reemplace el marcador de posición <access-token> por el token en los ejemplos siguientes.

Opción 2: Uso del portal de Fabric

Inicia sesión en el portal de Fabric para el inquilino en el que quieres probar y presiona F12 a fin de entrar en el modo para desarrolladores del explorador. En la consola, ejecute:

powerBIAccessToken

Copie el token y reemplace el marcador de posición <access-token> en los siguientes ejemplos por el token.

Crear una canalización

Crea una canalización en un área de trabajo especificada.

Solicitud de ejemplo:

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

Encabezados:

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

Carga útil:

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

Respuesta de ejemplo:

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

Creación de una canalización con definición

Crea una canalización con una definición de base64 en un área de trabajo especificada.

Solicitud de ejemplo:

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

Encabezados:

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

Carga útil:

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

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

Respuesta de ejemplo:

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

Obtención de canalización

Devuelve las propiedades de la canalización especificada.

Solicitud de ejemplo:

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

Encabezados:

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

Respuesta de ejemplo:

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

Obtención de canalización con definición

Devuelve la definición del elemento de canalización.

Solicitud de ejemplo:

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

Encabezados:

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

Respuesta de ejemplo:

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

Actualización de la canalización

Actualiza las propiedades de la canalización.

Solicitud de ejemplo:

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

Encabezados:

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

Carga útil:

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

Respuesta de ejemplo:

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

Actualización de canalización con definición

Actualiza la definición del elemento de canalización.

Solicitud de ejemplo:

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

Encabezados:

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

Carga útil:

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

Respuesta de ejemplo:

200 OK

Eliminación de la canalización

Elimina la canalización especificada.

Solicitud de ejemplo:

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

Encabezados:

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

Respuesta de ejemplo:

200 OK

Ejecución del trabajo de canalización a petición

Ejecuta una instancia de trabajo de canalización a petición.

Solicitud de ejemplo:

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

Encabezados:

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

Carga útil:

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

Respuesta de ejemplo:

202 Accepted

Obtención de instancia de trabajo de canalización

Obtiene la instancia de trabajo de la canalización singular.

Solicitud de ejemplo:

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

Encabezados:

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

Respuesta de ejemplo:

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

Cancelación de la instancia de trabajo de canalización

Cancela la instancia de trabajo de una canalización.

Solicitud de ejemplo:

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

Encabezados:

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

Respuesta de ejemplo:

* Ubicación: https://api.fabric.microsoft.com/v1/workspaces/<worksapceId>/items/<itemId>/jobs/instances/<jobInstanceId>Retry-after: 60

Ejecuciones de actividad de consulta

Ejemplo:

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

Cuerpo:

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

Nota

"id. de trabajo" es el mismo identificador creado y usado en las API públicas del programador de trabajos.

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

Soporte para el Nombre Principal de Servicio (SPN)

El Nombre Principal del Servicio (SPN) es una característica de identidad de seguridad que las aplicaciones o servicios utilizan para acceder a recursos específicos. En Fabric Data Factory, la compatibilidad con SPN es fundamental para habilitar el acceso seguro y automatizado a los orígenes de datos. Estos son algunos puntos clave sobre la compatibilidad con SPN:

Autenticación: los SPNs se usan para autenticar aplicaciones o servicios al acceder a fuentes de datos. Esto garantiza que solo las entidades autorizadas puedan acceder a los datos.
Configuración: Para usar SPNs, debe crear una entidad de servicio en Azure y concederle los permisos necesarios para acceder al origen de datos. Por ejemplo, si utiliza un lago de datos, la entidad de servicio necesita acceso de lector de datos de blobs de almacenamiento.
Conexión: Al configurar una conexión de datos en Fabric Data Factory, puede optar por autenticarse mediante un principal de servicio. Esto implica proporcionar el identificador de inquilino, el identificador de cliente y el secreto de cliente de la entidad de servicio.
Seguridad: El uso de SPNs mejora la seguridad al evitar el uso de credenciales embebidas en sus flujos de datos. También permite una mejor administración de los permisos de acceso y la auditoría de las actividades de acceso.

Para obtener información más detallada sobre cómo configurar y usar SPNs en Fabric Data Factory, consulte soporte de SPN en Data Factory.

Limitaciones actuales

Limitación del trabajo: las API de ejecución son invocables, pero la ejecución real nunca se realiza correctamente (al igual que ejecutar o actualizar desde la interfaz de usuario).
Elementos de Fabric que no son de Power BI: el área de trabajo debe estar en una capacidad de Fabric de soporte.
Crear un elemento: usa creationPayload o definition, pero no uses ambos al mismo tiempo.

Consulte el siguiente contenido para obtener más información sobre las API REST para canalizaciones de datos en Fabric Data Factory:

Compartir a través de

Funcionalidades de api REST para canalizaciones de datos en Fabric Data Factory

Casos de uso de API para canalizaciones de datos

Descripción de las API

Compatibilidad con CRUD

Introducción a las API REST para canalizaciones de datos

Obtenga un token de autorización

Opción 1: Uso de MSAL.Net

Opción 2: Uso del portal de Fabric

Crear una canalización

Creación de una canalización con definición

Obtención de canalización

Obtención de canalización con definición

Actualización de la canalización

Actualización de canalización con definición

Eliminación de la canalización

Ejecución del trabajo de canalización a petición

Obtención de instancia de trabajo de canalización

Cancelación de la instancia de trabajo de canalización

Ejecuciones de actividad de consulta

Soporte para el Nombre Principal de Servicio (SPN)

Limitaciones actuales

Contenido relacionado

Documentación

Tutoriales

Comentarios

Recursos adicionales