Partilhar via

API REST pública de espelhamento do Microsoft Fabric

  • Artigo

As APIs públicas para espelhamento de malha consistem em duas categorias: (1) operações CRUD para item de banco de dados espelhado de malha e (2) operações de início/parada e monitoramento. A principal documentação de referência online para APIs REST do Microsoft Fabric pode ser encontrada em Referências da API REST do Microsoft Fabric.

Nota

Essas APIs REST não se aplicam ao banco de dados espelhado do Azure Databricks.

Criar banco de dados espelhado

API REST - Itens - Criar banco de dados espelhado

Antes de criar um banco de dados espelhado, a conexão de fonte de dados correspondente é necessária. Se você ainda não tiver uma conexão, consulte Criar nova conexão usando o portal e use essa ID de conexão na definição a seguir. Você também pode consultar criar nova API REST de conexão para criar nova conexão usando APIs REST de malha.

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases

Corpo:

{
    "displayName": "Mirrored database 1",
    "description": "A mirrored database description",
    "definition": {
        "parts": [
            {
                "path": "mirroring.json",
                "payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

A propriedade payload no corpo JSON anterior é codificada em Base64. Você pode usar Base64 Encode and Decode para codificar. Os exemplos originais de definição JSON para diferentes tipos de fontes seguem:

Se desejar replicar tabelas seletivas em vez de todas as tabelas no banco de dados especificado, consulte o exemplo de definição JSON de replicação de tabelas especificadas.

Importante

Para espelhar dados do Banco de Dados SQL do Azure ou da Instância Gerenciada SQL do Azure, você também precisa fazer o seguinte antes de iniciar o espelhamento:

  1. Habilite o SAMI (System Assigned Managed Identity) do seu servidor lógico SQL do Azure ou da Instância Gerenciada SQL do Azure.
  2. Conceda a permissão de leitura e gravação SAMI ao banco de dados espelhado. Atualmente, você precisa fazer isso no portal do Fabric. Alternativley, você pode conceder a função de espaço de trabalho SAMI usando Adicionar API de Atribuição de Função de Espaço de Trabalho.

Exemplo de definição JSON de Snowflake

{
    "properties": {
        "source": {
            "type": "Snowflake",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
                "database": "xxxx"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        }
    }
}

Exemplo de definição JSON do Banco de Dados SQL do Azure

{
    "properties": {
        "source": {
            "type": "AzureSqlDatabase",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        }
    }
}

Exemplo de definição JSON da Instância Gerenciada SQL do Azure

{
    "properties": {
        "source": {
            "type": "AzureSqlMI",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        }
    }
}

Exemplo de definição JSON do Azure Cosmos DB

{
    "properties": {
        "source": {
            "type": "CosmosDb",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
                "database": "xxxx"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        }
    }
}

Exemplo de definição JSON de espelhamento aberto

{
    "properties": {
        "source": {
            "type": "GenericMirror",
            "typeProperties": {}
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "format": "Delta"
            }
        }
    }
}

Exemplo de definição JSON de replicação de tabelas especificadas

Os exemplos anteriores se aplicam ao cenário que replica automaticamente todas as tabelas no banco de dados especificado. Se desejar especificar as tabelas a serem replicadas, você poderá especificar a mountedTables propriedade, como no exemplo a seguir.

{
    "properties": {
        "source": {
            "type": "Snowflake",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
                "database": "xxxx"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        },
        "mountedTables": [
            {
                "source": {
                    "typeProperties": {
                        "schemaName": "xxxx",
                        "tableName": "xxxx"
                    }
                }
            }
        ]
    }
}

Resposta 201:

{ 
    "id": "<mirrored database ID>", 
    "type": "MirroredDatabase", 
    "displayName": "Mirrored database 1", 
    "description": "A mirrored database description", 
    "workspaceId": "<your workspace ID>" 
}

Excluir banco de dados espelhado

API REST - Itens - Excluir banco de dados espelhado

Exemplo:

DELETE https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>

Resposta 200: (Sem corpo)

Obter banco de dados espelhado

API REST - Itens - Obter banco de dados espelhado

Exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>

Resposta 200:

{
    "displayName": "Mirrored database 1",
    "description": "A mirrored database description.",
    "type": "MirroredDatabase",
    "workspaceId": "<your workspace ID>",
    "id": "<mirrored database ID>",
    "properties": {
        "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/<your workspace ID>/<mirrored database ID>/Tables",
        "sqlEndpointProperties": {
            "connectionString": "xxxx.xxxx.fabric.microsoft.com",
            "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
            "provisioningStatus": "Success"
        },
        "defaultSchema": "xxxx"
    }
}

Obter definição de banco de dados espelhado

API REST - Itens - Obter definição de banco de dados espelhado

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getDefinition

Resposta 200:

{ 
    "definition": { 
        "parts":[ 
            { 
                "path": "mirroring.json", 
                "payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0", 
                "payloadType": "InlineBase64" 
            } 
        ] 
    } 
}

Listar bancos de dados espelhados

API REST - Itens - Listar bancos de dados espelhados

Exemplo:

GET https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases

Resposta 200:

{ 
    "value": [ 
        {
            "displayName": "Mirrored database 1",
            "description": "A mirrored database description.",
            "type": "MirroredDatabase",
            "workspaceId": "<your workspace ID>",
            "id": "<mirrored database ID>",
            "properties": {
                "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/<your workspace ID>/<mirrored database ID>/Tables",
                "sqlEndpointProperties": {
                    "connectionString": "xxxx.xxxx.fabric.microsoft.com",
                    "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
                    "provisioningStatus": "Success"
                },
                "defaultSchema": "xxxx"
            }
        }
    ] 
}

Atualizar banco de dados espelhado

API REST - Itens - Atualizar banco de dados espelhado

Exemplo:

PATCH https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>

Corpo:

{
    "displayName": "MirroredDatabase's New name",
    "description": "A new description for mirrored database."
}

Resposta 200:

{
    "displayName": "MirroredDatabase's New name",
    "description": "A new description for mirrored database.",
    "type": "MirroredDatabase",
    "workspaceId": "<your workspace ID>",
    "id": "<mirrored database ID>"
}

Atualizar definição de banco de dados espelhado

API REST - Itens - Atualizar definição de banco de dados espelhado

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/updateDefinition

Corpo:

{ 
  "definition": { 
    "parts": [ 
      { 
        "path": "mirroring.json", 
        "payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0", 
        "payloadType": "InlineBase64" 
      } 
    ] 
  } 
}

Resposta 200: (Sem corpo)

Nota

Esta API suporta a adição/remoção de tabelas atualizando a mountedTables propriedade. Ele também suporta a atualização do ID de conexão de origem, nome do banco de dados e esquema padrão (essas três propriedades só podem ser atualizadas quando Get mirroring status api retorna Initialized/Stopped).

Obter status de espelhamento

API REST - Espelhamento - Obter status de espelhamento

Essa API retorna o status da instância de banco de dados espelhada. A lista de status disponíveis é fornecida em valores de MirroringStatus.

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getMirroringStatus

Resposta 200:

{
    "status": "Running"
}

Iniciar espelhamento

API REST - Espelhamento - Iniciar espelhamento

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/startMirroring

Resposta 200: (Sem corpo)

Nota

O espelhamento não pode ser iniciado quando acima Obter api de status de espelhamento retorna Initializing status.

Obter status de espelhamento de tabelas

API REST - Espelhamento - Obter status de espelhamento de tabelas

Se o espelhamento for iniciado e a API Obter status de espelhamento retornar Running o status, essa API retornará o status e as métricas da replicação de tabelas.

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getTablesMirroringStatus

Resposta 200:

{
    "continuationToken": null,
    "continuationUri": null,
    "data": [
        {
            "sourceSchemaName": "dbo",
            "sourceTableName": "test",
            "status": "Replicating",
            "metrics": {
                "processedBytes": 1247,
                "processedRows": 6,
                "lastSyncDateTime": "2024-10-08T05:07:11.0663362Z"
            }
        }
    ]
}

Parar o espelhamento

API REST - Espelhamento - Parar espelhamento

Exemplo:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/stopMirroring

Resposta 200: (Sem corpo)

Nota

Depois de interromper o espelhamento, você pode chamar Get mirroring status api para consultar o status do espelhamento.

Microsoft Fabric .NET SDK

O SDK do .NET que oferece suporte ao espelhamento de malha está disponível em Microsoft Fabric .NET SDK. A versão precisa ser >= 1.0.0-beta.11.

Limitações conhecidas

Atualmente, a autenticação de Entidade de Serviço/Identidade Gerenciada não é suportada se a região de origem do locatário estiver no Centro-Norte dos EUA ou no Leste dos EUA. Você pode usá-lo em outras regiões.

Conteúdos relacionados