Microsoft Fabric 鏡像公用 REST API

網狀架構鏡像的公用 API 包含兩個類別：(1) 適用於網狀架構鏡像資料庫項目的 CRUD 作業，以及 (2) 啟動/停止和監視作業。 Microsoft Fabric REST API 主要的線上參考文件可以在 Microsoft Fabric REST API 參考中找到。

注意

這些 REST API 不適用於來自 Azure Databricks 的鏡像資料庫。

建立鏡像資料庫

REST API - 專案 - 建立鏡像資料庫

建立鏡像資料庫之前，需要對應的數據源連線。 如果您還沒有連線，請參閱 使用入口網站 建立新的連線，並在下列定義中使用該聯機標識碼。 您也可以參考 建立新的連線 REST API ，以使用網狀架構 REST API 建立新的連線。

範例：

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

主體：

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

先前 JSON 主體中的承載屬性是以Base64編碼。 您可以使用 Base64編碼和譯碼 來編碼。 不同類型的來源的原始 JSON 定義範例如下：

• Snowflake 的 JSON 定義範例
• Azure SQL 資料庫 的 JSON 定義範例
• Azure SQL 受控執行個體 的 JSON 定義範例
• 適用於 PostgreSQL 的 Azure 資料庫彈性伺服器的 JSON 定義範例
• Azure Cosmos DB 的 JSON 定義範例
• 開啟鏡像的 JSON 定義範例

如果您想要復寫選擇性數據表，而不是指定資料庫中的所有數據表，請參閱 複寫指定數據表的 JSON 定義範例。

重要

若要對 Azure SQL 資料庫或 Azure SQL 受控執行個體進行資料鏡像，您需要在開始鏡像之前先完成以下步驟：

1. 啟用 Azure SQL 邏輯伺服器或 Azure SQL 受控執行個體 的系統指派受控識別（SAMI）。
2. 授予 SAMI 鏡像資料庫 讀取和寫入的許可權。 目前您需要在網狀架構入口網站上執行此動作。 或者，您可以使用 新增工作區角色分配 API來指派 SAMI 的工作區角色。

注意

defaultSchema 屬性指出是否要從源資料庫複寫架構階層。

Snowflake 的 JSON 定義範例

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

Azure SQL 資料庫 的 JSON 定義範例

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

Azure SQL 受控執行個體 的 JSON 定義範例

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

適用於 PostgreSQL 的 Azure 資料庫彈性伺服器的 JSON 定義範例

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

Azure Cosmos DB 的 JSON 定義範例

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

SQL Server 2025 鏡像資料庫的 JSON 定義範例

此範例僅適用於 SQL Server 2025 的網狀架構鏡像。

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

SQL Server 2016-2022 鏡像資料庫的 JSON 定義範例

此範例適用於 SQL Server 2016-2022 的網狀架構鏡像。

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

開啟鏡像的 JSON 定義範例

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

複寫指定數據表的 JSON 定義範例

上述範例適用於自動復寫指定資料庫中所有數據表的案例。 如果您想要指定要復寫的數據表，您可以指定 mountedTables 屬性，如下列範例所示。

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

回應 201：

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

刪除鏡像資料庫

REST API - 項目 - 刪除鏡像資料庫

範例：

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

回應 200：（沒有內文）

取得鏡像化的資料庫

REST API - 項目 - 取得鏡像資料庫

範例：

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

回應 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"
    }
}

取得鏡像資料庫定義

REST API - 項目 - 取得鏡像資料庫定義

範例：

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

回應 200：

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

列出鏡像資料庫

REST API - 項目 - 列出鏡像資料庫

範例：

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

回應 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"
            }
        }
    ] 
} 

更新鏡像資料庫

REST API - 專案 - 更新鏡像資料庫

範例：

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

主體：

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

回應 200：

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

更新鏡像資料庫定義

REST API - 專案 - 更新鏡像資料庫定義

範例：

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

主體：

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

回應 200：（沒有內文）

先前 JSON 主體中的承載屬性是以Base64編碼。 您可以使用 Base64編碼和譯碼 來編碼。

注意

此 API 支援藉由重新整理 mountedTables 屬性來新增/移除資料表。 它也支援更新來源連線標識碼、資料庫名稱和默認架構（這三個屬性只能在 取得鏡像狀態時更新， API 傳回 Initialized/Stopped）。

設定資料保留

您可以使用 屬性來設定鏡像數據的retentionInDays保留期間。 預設值為七天。 允許的值為介於 1 到 30 之間的整數。

Base64 編碼之前的 JSON 定義範例：

{
    "properties": {
        "source": {...},
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta",
                "retentionInDays": 1
            }
        }
    }
}

取得鏡像狀態

REST API - 鏡像 - 取得鏡像狀態

此 API 會傳回鏡像資料庫實例的狀態。 可用的狀態清單會以 MirroringStatus 的值提供。

範例：

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

回應 200：

{
    "status": "Running"
}

開始同步顯示

REST API - 資料同步 - 開始同步

範例：

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

回應 200：（沒有內文）

注意

當上述 取得鏡像狀態 API 傳回 Initializing 狀態時，就無法啟動鏡像。

取得數據表鏡像狀態

REST API - 鏡像 - 取得數據表鏡像狀態

如果鏡像啟動且 取得鏡像狀態 API 會 Running 傳回狀態，此 API 會傳回數據表復寫的狀態和計量。

範例：

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

回應 200：

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

停止同步

REST API（REST 應用程式介面）- 同步 - 停止資料同步

範例：

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

回應 200：（沒有內文）

注意

停止鏡像之後，您可以呼叫 取得鏡像狀態 API 來查詢鏡像狀態。

Microsoft Fabric .NET SDK

支援網狀架構鏡像的 .NET SDK 可在 Microsoft Fabric .NET SDK 取得。 版本必須是 >= 1.0.0-beta.11。

相關內容

• REST API - 項目