Microsoft Fabric mirroring public REST API
The public APIs for Fabric mirroring consist of two categories: (1) CRUD operations for Fabric mirrored database item and (2) Start/stop and monitoring operations. The primary online reference documentation for Microsoft Fabric REST APIs can be found in Microsoft Fabric REST API references.
Note
These REST APIs don't apply to mirrored database from Azure Databricks.
Create mirrored database
REST API - Items - Create mirrored database
Before you create mirrored database, the corresponding data source connection is needed. If you don't have a connection yet, refer to create new connection using portal and use that connection ID in the following definition. You can also refer to create new connection REST API to create new connection using Fabric REST APIs.
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases
Body:
{
"displayName": "Mirrored database 1",
"description": "A mirrored database description",
"definition": {
"parts": [
{
"path": "mirroring.json",
"payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0",
"payloadType": "InlineBase64"
}
]
}
}
The payload property in previous JSON body is Base64 encoded. You can use Base64 Encode and Decode to encode. The original JSON definition examples for different types of sources follow:
- JSON definition example of Snowflake
- JSON definition example of Azure SQL Database
- JSON definition example of Azure SQL Managed Instance
- JSON definition example of Azure Cosmos DB
- JSON definition example of open mirroring
If you want to replicate selective tables instead of all the tables in the specified database, refer to JSON definition example of replicating specified tables.
Important
To mirror data from Azure SQL Database or Azure SQL Managed Instance, you need to also do the following before start mirroring:
- Enable System Assigned Managed Identity (SAMI) of your Azure SQL logical server or Azure SQL Managed Instance.
- Grant the SAMI Read and Write permission to the mirrored database. Currently you need to do this on the Fabric portal. Alternativley, you can grant SAMI workspace role using Add Workspace Role Assignment API.
Note
defaultSchema property indicates whether to replicate the schema hierarchy from the source database. If your Fabric capacity region is in North Central US or East US, please do not specify this property as currently this feature is not supported in those regions.
JSON definition example of Snowflake
{
"properties": {
"source": {
"type": "Snowflake",
"typeProperties": {
"connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
"database": "xxxx"
}
},
"target": {
"type": "MountedRelationalDatabase",
"typeProperties": {
"defaultSchema": "xxxx",
"format": "Delta"
}
}
}
}
JSON definition example of Azure SQL Database
{
"properties": {
"source": {
"type": "AzureSqlDatabase",
"typeProperties": {
"connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
"landingZone":{
"type":"MountedRelationalDatabase"
}
}
},
"target": {
"type": "MountedRelationalDatabase",
"typeProperties": {
"defaultSchema": "xxxx",
"format": "Delta"
}
}
}
}
JSON definition example of Azure SQL Managed Instance
{
"properties": {
"source": {
"type": "AzureSqlMI",
"typeProperties": {
"connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
"landingZone":{
"type":"MountedRelationalDatabase"
}
}
},
"target": {
"type": "MountedRelationalDatabase",
"typeProperties": {
"defaultSchema": "xxxx",
"format": "Delta"
}
}
}
}
JSON definition example of Azure Cosmos DB
{
"properties": {
"source": {
"type": "CosmosDb",
"typeProperties": {
"connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
"database": "xxxx"
}
},
"target": {
"type": "MountedRelationalDatabase",
"typeProperties": {
"defaultSchema": "xxxx",
"format": "Delta"
}
}
}
}
JSON definition example of open mirroring
{
"properties": {
"source": {
"type": "GenericMirror",
"typeProperties": {}
},
"target": {
"type": "MountedRelationalDatabase",
"typeProperties": {
"format": "Delta"
}
}
}
}
JSON definition example of replicating specified tables
The previous examples apply to the scenario that automatically replicates all the tables in the specified database. If you want to specify the tables to replicate, you can specify the mountedTables property, as in the following example.
{
"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"
}
}
}
]
}
}
Response 201:
{
"id": "<mirrored database ID>",
"type": "MirroredDatabase",
"displayName": "Mirrored database 1",
"description": "A mirrored database description",
"workspaceId": "<your workspace ID>"
}
Delete mirrored database
REST API - Items - Delete mirrored database
Example:
DELETE https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>
Response 200: (No body)
Get mirrored database
REST API - Items - Get mirrored database
Example:
GET https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>
Response 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"
}
}
Get mirrored database definition
REST API - Items - Get mirrored database definition
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getDefinition
Response 200:
{
"definition": {
"parts":[
{
"path": "mirroring.json",
"payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0",
"payloadType": "InlineBase64"
}
]
}
}
List mirrored databases
REST API - Items - List mirrored databases
Example:
GET https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases
Response 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"
}
}
]
}
Update mirrored database
REST API - Items - Update mirrored database
Example:
PATCH https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>
Body:
{
"displayName": "MirroredDatabase's New name",
"description": "A new description for mirrored database."
}
Response 200:
{
"displayName": "MirroredDatabase's New name",
"description": "A new description for mirrored database.",
"type": "MirroredDatabase",
"workspaceId": "<your workspace ID>",
"id": "<mirrored database ID>"
}
Update mirrored database definition
REST API - Items - Update mirrored database definition
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/updateDefinition
Body:
{
"definition": {
"parts": [
{
"path": "mirroring.json",
"payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0",
"payloadType": "InlineBase64"
}
]
}
}
Response 200: (No body)
Note
This API supports adding/removing tables by refreshing the mountedTables property. It also supports updating the source connection ID, database name and default schema (these three properties can only be updated when Get mirroring status api returns Initialized/Stopped).
Get mirroring status
REST API - Mirroring - Get mirroring status
This API returns the status of mirrored database instance. The list of available statuses are provided at values of MirroringStatus.
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getMirroringStatus
Response 200:
{
"status": "Running"
}
Start mirroring
REST API - Mirroring - Start mirroring
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/startMirroring
Response 200: (No body)
Note
Mirroring can not be started when above Get mirroring status api returns Initializing status.
Get tables mirroring status
REST API - Mirroring - Get tables mirroring status
If mirroring is started and Get mirroring status API returns Running status, this API returns the status and metrics of tables replication.
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getTablesMirroringStatus
Response 200:
{
"continuationToken": null,
"continuationUri": null,
"data": [
{
"sourceSchemaName": "dbo",
"sourceTableName": "test",
"status": "Replicating",
"metrics": {
"processedBytes": 1247,
"processedRows": 6,
"lastSyncDateTime": "2024-10-08T05:07:11.0663362Z"
}
}
]
}
Stop mirroring
REST API - Mirroring - Stop mirroring
Example:
POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/stopMirroring
Response 200: (No body)
Note
After stopping mirroring, you can call Get mirroring status api to query the mirroring status.
Microsoft Fabric .NET SDK
The .NET SDK that supports Fabric mirroring is available at Microsoft Fabric .NET SDK. The version needs to be >= 1.0.0-beta.11.
Known limitations
Currently Service Principal/Managed Identity authentication is not supported if your tenant home region is in North Central US or East US. You can use it in other regions.