Compartilhar via

Funcionalidades da API REST para pipelines de dados no Fabric Data Factory

O Fabric Data Factory fornece um conjunto robusto de APIs que permitem que os usuários automatizem e gerenciem os pipelines de dados com eficiência. Essas APIs permitem uma integração perfeita com várias fontes de dados e serviços, permitindo que os usuários criem, atualizem e monitorem os fluxos de trabalho de dados programaticamente. As APIs são compatíveis com uma ampla gama de operações, inclusive CRUD (Create, Read, Update, and Delete) de pipeline, agendamento e monitoramento. Isso torna mais fácil para os usuários gerenciar os processos de integração de dados.

Casos de uso de API para pipelines de dados

As APIs para pipelines no Fabric Data Factory podem ser usadas em vários cenários:

  • Implantação automatizada: automatizar a implantação de pipelines de dados em diferentes ambientes (desenvolvimento, teste, produção) usando práticas de CI/CD.
  • Monitoramento e alertas: configure sistemas automatizados de monitoramento e alertas para acompanhar o status dos pipelines de dados e receber notificações, se ocorrerem falhas ou problemas de desempenho.
  • Integração de dados: integre dados de várias fontes, como bancos de dados, data lakes e serviços de nuvem, em um pipeline de dados unificado para processamento e análise.
  • Tratamento de erros: implemente mecanismos personalizados de tratamento de erros e repetição para garantir que os pipelines de dados sejam executados sem problemas e se recuperem de falhas.

Noções básicas sobre APIs

Para usar efetivamente as APIs para pipelines no Fabric Data Factory, é essencial entender os principais conceitos e componentes:

  • Pontos de extremidade: os pontos de extremidade da API fornecem acesso a várias operações de pipeline, como criar, atualizar e excluir pipelines.
  • Autenticação: proteger o acesso às APIs usando mecanismos de autenticação como OAuth ou chaves de API.
  • Solicitações e respostas: entenda a estrutura de solicitações e respostas da API, inclusive os parâmetros necessários e a saída esperada.
  • Limites de taxa: conheça os limites de taxa impostos ao uso da API para evitar exceder o número permitido de solicitações.

Suporte ao CRUD

CRUD significa Create, Read, Update, and Delete (Criar, Ler, Atualizar e Excluir), que são as quatro operações básicas que podem ser executadas nos dados. No Fabric Data Factory, as operações CRUD têm suporte por meio da API do Fabric para Data Factory. Essas APIs permitem que os usuários gerenciem os pipelines programaticamente. Estes são alguns pontos importantes sobre o suporte ao CRUD:

  • Criar: crie novos pipelines usando a API. Isso envolve definir a estrutura do pipeline, especificar fontes de dados, transformações e destinos.
  • Ler: recupere informações sobre os pipelines existentes. Isso inclui detalhes sobre a configuração, status e histórico de execução.
  • Atualizar: atualize os pipelines existentes. Isso pode envolver a modificação da estrutura do pipeline, a alteração das fontes de dados ou a atualização da lógica de transformação.
  • Excluir: exclua os pipelines que não são mais necessários. Isso ajuda no gerenciamento e limpeza de recursos.

A documentação de referência online principal para APIs REST do Microsoft Fabric pode ser encontrada na documentação da API REST do Microsoft Fabric.

Introdução às APIs REST para pipelines de dados

Os exemplos a seguir mostram como criar, atualizar e gerenciar pipelines usando as APIs do Fabric Data Factory.

Obter um token de autorização

Antes de usar as outras APIs REST, você precisa ter o token de portador.

Importante

Nos exemplos a seguir, verifique se a palavra 'Portador' (com um espaço) precede o próprio token de acesso. Ao usar um cliente de API e selecionar "Bearer Token" como o tipo de autenticação, 'Bearer ' é inserido automaticamente, e requer apenas que o token de acesso seja fornecido.

Opção 1: Usando a MSAL.Net

Confira a seção Obter Token do início rápido da API do Fabric como exemplo de como obter o token de autorização MSAL.

Use MSAL.Net para adquirir um token do Microsoft Entra ID para o serviço do Fabric com os seguintes escopos: Workspace.ReadWrite.All, Item.ReadWrite.All. Para obter mais informações sobre aquisição de tokens com a MSAL.Net, consulte Aquisição de token – Biblioteca de Autenticação da Microsoft para .NET.

Copie o token da propriedade AccessToken e substitua o marcador de posição <access-token> nos exemplos abaixo pelo token.

Opção 2: usando o portal do Fabric

Entre no portal do Fabric para o Locatário no qual você deseja testar e pressione F12 para entrar no modo de desenvolvedor do navegador. No console, execute:

powerBIAccessToken

Copie o token e substitua o espaço reservado <access-token> nos exemplos a seguir pelo token.

Criar um pipeline

Crie um pipeline em um espaço de trabalho especificado.

Solicitação de exemplo:

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

Cabeçalhos:

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

Conteúdo:

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

Resposta de exemplo:

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

Criar um pipeline com definição

Crie um pipeline com uma definição base64 em um workspace especificado.

Solicitação de exemplo:

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

Cabeçalhos:

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

Conteúdo:

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

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

Resposta de exemplo:

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

Obter pipeline

Retorna as propriedades do pipeline especificado.

Solicitação de exemplo:

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

Cabeçalhos:

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

Resposta de exemplo:

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

Obter pipeline com definição

Retorna a definição do item de pipeline.

Solicitação de exemplo:

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

Cabeçalhos:

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

Resposta de exemplo:

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

Atualizar pipeline

Atualiza as propriedades do pipeline.

Solicitação de exemplo:

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

Cabeçalhos:

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

Conteúdo:

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

Resposta de exemplo:

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

Atualizar pipeline com definição

Atualiza a definição do item de pipeline.

Solicitação de exemplo:

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

Cabeçalhos:

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

Conteúdo:

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

Resposta de exemplo:

200 OK

Excluir pipeline

Exclui o pipeline especificado.

Solicitação de exemplo:

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

Cabeçalhos:

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

Resposta de exemplo:

200 OK

Executar trabalho de pipeline sob demanda

Executa a instância de trabalho de pipeline sob demanda.

Solicitação de exemplo:

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

Cabeçalhos:

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

Conteúdo:

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

Resposta de exemplo:

202 Accepted

Obter instância de trabalho do pipeline

Obtém a instância de trabalho do pipeline singular.

Solicitação de exemplo:

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

Cabeçalhos:

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

Resposta de exemplo:

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

Cancelar instância de trabalho do pipeline

Cancela a instância de trabalho de um pipeline.

Solicitação de exemplo:

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

Cabeçalhos:

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

Resposta de exemplo:

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

Execuções de atividade de consulta

Exemplo:

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

Corpo:

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

Nota

"id do trabalho" é a mesma ID criada e usada nas APIs Públicas do Agendador de Trabalhos

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

Suporte ao SPN (nome da entidade de serviço)

O SPN (Nome da Entidade de Serviço) é um recurso de identidade de segurança usado por aplicativos ou serviços para acessar recursos específicos. No Fabric Data Factory, o suporte ao SPN é crucial para habilitar o acesso seguro e automatizado a fontes de dados. Aqui estão alguns pontos importantes sobre o suporte ao SPN:

  • Autenticação: os SPNs são usados para autenticar aplicativos ou serviços ao acessar fontes de dados. Isso garante que somente entidades autorizadas possam acessar os dados.
  • Configuração Para usar SPNs, você precisa criar um principal de serviço no Azure e conceder-lhe as permissões necessárias para acessar a fonte de dados. Por exemplo, se você estiver usando um data lake, a entidade de serviço precisará ter acesso de leitor de dados no blob de armazenamento.
  • Conexão: ao configurar uma conexão de dados no Data Factory do Fabric, você pode optar por se autenticar usando uma entidade de serviço. Isso envolve fornecer a ID do locatário, a ID do cliente e o segredo do cliente da entidade de serviço.
  • Segurança: o uso de SPNs aprimora a segurança evitando o uso de credenciais codificadas em seus fluxos de dados. Ele também permite um melhor gerenciamento de permissões de acesso e auditoria de atividades de acesso.

Para obter informações mais detalhadas sobre como configurar e usar SPNs no Fabric Data Factory, consulte o suporte ao SPN no Data Factory.

Limitações atuais

  • Limitação de TRABALHO: as APIs de execução são invocáveis, mas a execução real nunca é bem-sucedida (assim como executar/atualizar na interface do usuário).
  • Itens que não são do Power BI Fabric: o workspace deve estar em uma capacidade do Fabric compatível.
  • Criação de um item: use creationPayload ou definição, mas não use ambos ao mesmo tempo.

Conteúdo relacionado

Consulte o seguinte conteúdo para obter mais informações sobre APIs REST para pipelines de dados no Fabric Data Factory:

Documentação

Tutoriais