Edit

Share via

Microsoft Fabric mirroring public REST API

  • Article

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:

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:

  1. Enable System Assigned Managed Identity (SAMI) of your Azure SQL logical server or Azure SQL Managed Instance.
  2. 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.

Related content