Connections - Create Connection

参考

服务:: Core

API 版本:: v1

注意

此 API 以预览版提供。

创建连接。
若要加密凭据，请参阅以编程方式配置凭据。

权限

如果创建网关连接，调用方必须具有网关的权限。

所需的委派范围

Connection.ReadWrite.All

Microsoft Entra 支持的标识

此 API 支持本节中列出的Microsoft 标识。

身份	支持
用户	是的
服务主体和托管标识	是的

接口

POST https://api.fabric.microsoft.com/v1/connections

请求正文

请求正文可以为下列任一内容：

名称	说明
CreateCloudConnectionRequest
CreateOnPremisesConnectionRequest
CreateVirtualNetworkGatewayConnectionRequest

CreateCloudConnectionRequest

名称	必需	类型	说明
connectionDetails	True	CreateConnectionDetails	连接的连接详细信息。
connectivityType	True	string: ShareableCloud	连接的连接类型。
credentialDetails	True	CreateCredentialDetails	连接的凭据详细信息。
displayName	True	string	连接的显示名称。最大长度为 200 个字符。
privacyLevel		PrivacyLevel	（可选）连接的隐私级别。如果未传递任何值，则此值设置为“组织”。

CreateOnPremisesConnectionRequest

名称	必需	类型	说明
connectionDetails	True	CreateConnectionDetails	连接的连接详细信息。
connectivityType	True	string: OnPremisesGateway	连接的连接类型。
credentialDetails	True	CreateOnPremisesCredentialDetails	连接的凭据详细信息。
displayName	True	string	连接的显示名称。最大长度为 200 个字符。
gatewayId	True	string uuid	创建连接的本地网关的主网关的对象 ID。
privacyLevel		PrivacyLevel	（可选）连接的隐私级别。如果未传递任何值，则此值设置为“组织”。

CreateVirtualNetworkGatewayConnectionRequest

名称	必需	类型	说明
connectionDetails	True	CreateConnectionDetails	连接的连接详细信息。
connectivityType	True	string: VirtualNetworkGateway	连接的连接类型。
credentialDetails	True	CreateCredentialDetails	连接的凭据详细信息。
displayName	True	string	连接的显示名称。最大长度为 200 个字符。
gatewayId	True	string uuid	创建连接的虚拟网络网关的对象 ID。
privacyLevel		PrivacyLevel	（可选）连接的隐私级别。如果未传递任何值，则此值设置为“组织”。

响应

名称	类型	说明
201 Created	Connection	创建。作成功。
Other Status Codes	ErrorResponse	常见错误代码： DuplicateConnectionName - 连接名称已在使用中。 InvalidConnectionDetails - 提供的 ConnectionDetails 输入无效。 InvalidCredentialDetails - 提供的 CredentialDetails 输入无效。 IncorrectCredentials - 无法使用凭据输入建立连接。 CreateGatewayConnectionFailed - 无法创建网关连接。

名称

类型

说明

201 Created

Connection

创建。作成功。

Other Status Codes

ErrorResponse

常见错误代码：

DuplicateConnectionName - 连接名称已在使用中。
InvalidConnectionDetails - 提供的 ConnectionDetails 输入无效。
InvalidCredentialDetails - 提供的 CredentialDetails 输入无效。
IncorrectCredentials - 无法使用凭据输入建立连接。
CreateGatewayConnectionFailed - 无法创建网关连接。

示例

Cloud example

Virtual network gateway example

Cloud example

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/connections

{
  "connectivityType": "ShareableCloud",
  "displayName": "ContosoCloudConnection",
  "connectionDetails": {
    "type": "SQL",
    "creationMethod": "SQL",
    "parameters": [
      {
        "dataType": "Text",
        "name": "server",
        "value": "contoso.database.windows.net"
      },
      {
        "dataType": "Text",
        "name": "database",
        "value": "sales"
      }
    ]
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false,
    "credentials": {
      "credentialType": "Basic",
      "username": "admin",
      "password": "********"
    }
  }
}

示例响应

状态代码:: 201

{
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "displayName": "ContosoCloudConnection",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

Virtual network gateway example

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/connections

{
  "connectivityType": "VirtualNetworkGateway",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "displayName": "ContosoVirtualNetworkGatewayConnection",
  "connectionDetails": {
    "type": "SQL",
    "creationMethod": "SQL",
    "parameters": [
      {
        "dataType": "Text",
        "name": "server",
        "value": "contoso.database.windows.net"
      },
      {
        "dataType": "Text",
        "name": "database",
        "value": "sales"
      }
    ]
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "singleSignOnType": "None",
    "connectionEncryption": "Encrypted",
    "skipTestConnection": false,
    "credentials": {
      "credentialType": "Basic",
      "username": "admin",
      "password": "*********"
    }
  }
}

示例响应

状态代码:: 201

{
  "id": "eeec9a3a-6ef5-4e2b-bb6a-0060bd2f0172",
  "displayName": "ContosoVirtualNetworkGatewayConnection",
  "gatewayId": "93491300-cfbd-402f-bf17-9ace59a92354",
  "connectivityType": "VirtualNetworkGateway",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "Encrypted",
    "skipTestConnection": false
  }
}

定义

名称	说明
AnonymousCredentials	匿名 CredentialType 的凭据。
BasicCredentials	Basic CredentialType 的凭据。
Connection
ConnectionDetailsBooleanParameter	布尔数据类型的 ConnectionDetailsParameter。
ConnectionDetailsDateParameter	date dataType 的 ConnectionDetailsParameter。
ConnectionDetailsDateTimeParameter	dateTime dataType 的 ConnectionDetailsParameter。
ConnectionDetailsDateTimeZoneParameter	dateTimeZone dataType 的 ConnectionDetailsParameter。
ConnectionDetailsDurationParameter	Duration dataType 的 ConnectionDetailsParameter。
ConnectionDetailsNumberParameter	number dataType 的 ConnectionDetailsParameter。
ConnectionDetailsTextParameter	text dataType 的 ConnectionDetailsParameter。
ConnectionDetailsTimeParameter	time dataType 的 ConnectionDetailsParameter。
ConnectionEncryption	连接的连接加密类型。可能会随着时间的推移添加其他连接加密值。
ConnectivityType	连接的连接类型。可能会随着时间的推移添加其他连接类型。
CreateCloudConnectionRequest
CreateConnectionDetails	创建作的连接详细信息输入。
CreateCredentialDetails	用于创建连接的凭据详细信息输入。
CreateOnPremisesConnectionRequest
CreateOnPremisesCredentialDetails	用于创建本地网关连接的凭据详细信息输入。
CreateVirtualNetworkGatewayConnectionRequest
CredentialType	连接的凭据类型。可能会随着时间的推移添加其他凭据类型。
DataType	连接创建参数值的数据类型。可能会随着时间的推移添加其他数据类型值。
ErrorRelatedResource	与错误相关的资源详细信息对象。
ErrorResponse	错误响应。
ErrorResponseDetails	错误响应详细信息。
KeyCredentials	Key CredentialType 的凭据。
ListConnectionDetails	列表作的连接详细信息输出。
ListCredentialDetails	提取连接时返回的凭据详细信息。
OnPremisesCredentialEntry	网关 ID 及其加密的序列化凭据。
OnPremisesGatewayCredentials	用于通过本地网关进行身份验证的凭据。
PrivacyLevel	连接的隐私级别设置。可能会随着时间的推移添加其他隐私级别。
ServicePrincipalCredentials	ServicePrincipal CredentialType 的凭据。
SharedAccessSignatureCredentials	SharedAccessSignature CredentialType 的凭据。
SingleSignOnType	连接的单一登录类型。可能会随着时间的推移添加其他单一登录类型。
WindowsCredentials	Windows CredentialType 的凭据。
WindowsWithoutImpersonationCredentials	WindowsWithoutImpersonation CredentialType 的凭据。
WorkspaceIdentityCredentials	WorkspaceIdentity CredentialType 的凭据。

AnonymousCredentials

Object

匿名 CredentialType 的凭据。

名称	类型	说明
credentialType	string: Anonymous	连接的凭据类型。

BasicCredentials

Object

Basic CredentialType 的凭据。

名称	类型	说明
credentialType	string: Basic	连接的凭据类型。
password	string	密码。
username	string	用户名。

Connection

Object

名称	类型	说明
connectionDetails	ListConnectionDetails	连接的连接详细信息。
connectivityType	ConnectivityType	连接的连接类型。
credentialDetails	ListCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。
gatewayId	string uuid	连接的网关对象 ID。
id	string uuid	连接的对象 ID。
privacyLevel	PrivacyLevel	连接的隐私级别。

ConnectionDetailsBooleanParameter

Object

布尔数据类型的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: Boolean	参数的数据类型。
name	string	参数的名称。
value	boolean	布尔值。

ConnectionDetailsDateParameter

Object

date dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: Date	参数的数据类型。
name	string	参数的名称。
value	string date	使用 YYYY-MM-DD 格式的日期值。

ConnectionDetailsDateTimeParameter

Object

dateTime dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: DateTime	参数的数据类型。
name	string	参数的名称。
value	string date-time	使用 YYYY-MM-DDTHH：mm：ss 的日期时间值。FFFZ 格式。

ConnectionDetailsDateTimeZoneParameter

Object

dateTimeZone dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: DateTimeZone	参数的数据类型。
name	string	参数的名称。
value	string date-time-offset	使用 YYYY-MM-DDTHH：mm：ss 的日期时区值。FFF±hh：mm 格式。

ConnectionDetailsDurationParameter

Object

Duration dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: Duration	参数的数据类型。
name	string	参数的名称。
value	string time-span	使用 [-]P（n）DT（n）H（n）M（n）S 格式的持续时间值。例如：P3DT4H30M10S（3 天、4 小时、30 分钟和 10 秒）。

ConnectionDetailsNumberParameter

Object

number dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: Number	参数的数据类型。
name	string	参数的名称。
value	number	数字值。

ConnectionDetailsTextParameter

Object

text dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: Text	参数的数据类型。
name	string	参数的名称。
value	string	文本值。

ConnectionDetailsTimeParameter

Object

time dataType 的 ConnectionDetailsParameter。

名称	类型	说明
dataType	string: Time	参数的数据类型。
name	string	参数的名称。
value	string time	使用 HH：mm：ss 的时间值。FFFZ 格式。

ConnectionEncryption

Enumeration

连接的连接加密类型。可能会随着时间的推移添加其他连接加密值。

值	说明
Any	首先使用加密连接进行连接尝试，如果失败，则回退到未加密的连接。
Encrypted	连接尝试是使用加密连接进行的。
NotEncrypted	连接尝试是使用未加密的连接进行的。

ConnectivityType

Enumeration

连接的连接类型。可能会随着时间的推移添加其他连接类型。

值	说明
Automatic	连接使用隐式数据连接通过云进行连接。此选项仅适用于使用单一 Sign-On（SSO）的特定方案。”
None	连接未绑定
OnPremisesGateway	连接通过本地数据网关进行连接。
OnPremisesGatewayPersonal	连接通过个人本地数据网关进行连接。
PersonalCloud	连接通过云进行连接，无法与他人共享。
ShareableCloud	连接通过云进行连接，可与其他人共享。
VirtualNetworkGateway	连接通过虚拟网络数据网关进行连接。

CreateCloudConnectionRequest

Object

名称	类型	说明
connectionDetails	CreateConnectionDetails	连接的连接详细信息。
connectivityType	string: ShareableCloud	连接的连接类型。
credentialDetails	CreateCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。最大长度为 200 个字符。
privacyLevel	PrivacyLevel	（可选）连接的隐私级别。如果未传递任何值，则此值设置为“组织”。

CreateConnectionDetails

Object

创建作的连接详细信息输入。

名称	类型	说明
creationMethod	string	用于创建连接的创建方法。
parameters	ConnectionDetailsParameter[]: ConnectionDetailsBooleanParameter[] ConnectionDetailsDateParameter[] ConnectionDetailsDateTimeParameter[] ConnectionDetailsDateTimeZoneParameter[] ConnectionDetailsDurationParameter[] ConnectionDetailsNumberParameter[] ConnectionDetailsTextParameter[] ConnectionDetailsTimeParameter[]	连接参数列表。
type	string	连接的类型。

CreateCredentialDetails

Object

用于创建连接的凭据详细信息输入。

名称	类型	说明
connectionEncryption	ConnectionEncryption	（可选）测试连接期间使用的连接加密设置。如果未传递任何值，则不会加密连接。
credentials	Credentials: AnonymousCredentials BasicCredentials KeyCredentials ServicePrincipalCredentials SharedAccessSignatureCredentials WindowsCredentials WindowsWithoutImpersonationCredentials WorkspaceIdentityCredentials	连接的凭据。
singleSignOnType	SingleSignOnType	（可选）连接的单一登录类型。如果未传递任何值，则连接不使用单一登录。
skipTestConnection	boolean	连接是否应在创建和更新期间跳过测试连接。 True - 跳过测试连接，False - 请勿跳过测试连接。如果未传递任何值，则此值设置为“False”。

CreateOnPremisesConnectionRequest

Object

名称	类型	说明
connectionDetails	CreateConnectionDetails	连接的连接详细信息。
connectivityType	string: OnPremisesGateway	连接的连接类型。
credentialDetails	CreateOnPremisesCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。最大长度为 200 个字符。
gatewayId	string uuid	创建连接的本地网关的主网关的对象 ID。
privacyLevel	PrivacyLevel	（可选）连接的隐私级别。如果未传递任何值，则此值设置为“组织”。

CreateOnPremisesCredentialDetails

Object

用于创建本地网关连接的凭据详细信息输入。

名称	类型	说明
connectionEncryption	ConnectionEncryption	（可选）测试连接期间使用的连接加密设置。如果未传递任何值，则不会加密连接。
credentials	OnPremisesGatewayCredentials	连接的凭据。
singleSignOnType	SingleSignOnType	（可选）连接的单一登录类型。如果未传递任何值，则连接不使用单一登录。
skipTestConnection	boolean	连接是否应在创建和更新期间跳过测试连接。 True - 跳过测试连接，False - 请勿跳过测试连接。如果未传递任何值，则此值设置为“False”。

CreateVirtualNetworkGatewayConnectionRequest

Object

名称	类型	说明
connectionDetails	CreateConnectionDetails	连接的连接详细信息。
connectivityType	string: VirtualNetworkGateway	连接的连接类型。
credentialDetails	CreateCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。最大长度为 200 个字符。
gatewayId	string uuid	创建连接的虚拟网络网关的对象 ID。
privacyLevel	PrivacyLevel	（可选）连接的隐私级别。如果未传递任何值，则此值设置为“组织”。

CredentialType

Enumeration

连接的凭据类型。可能会随着时间的推移添加其他凭据类型。

值	说明
Anonymous	连接使用匿名身份验证进行连接。
Basic	连接使用基本身份验证进行连接。
Key	连接使用密钥身份验证进行连接。
OAuth2	连接使用 OAuth 2.0 身份验证进行连接。
ServicePrincipal	连接使用服务主体身份验证进行连接。
SharedAccessSignature	连接使用共享访问签名（SAS）身份验证进行连接。
Windows	连接使用 Windows 身份验证进行连接。仅支持本地网关。
WindowsWithoutImpersonation	连接使用 Windows（没有模拟选项）身份验证进行连接。仅支持本地网关（个人模式）。
WorkspaceIdentity	连接使用工作区标识身份验证进行连接。

DataType

Enumeration

连接创建参数值的数据类型。可能会随着时间的推移添加其他数据类型值。

值	说明
Boolean	使用布尔值作为参数输入值。 False - 值为 false、True - 值为 true。
Date	使用日期作为参数输入值，使用 YYYY-MM-DD 格式。
DateTime	使用日期时间作为参数输入值，使用 YYYY-MM-DDTHH：mm：ss。FFFZ 格式。
DateTimeZone	使用日期时区作为参数输入值，使用 YYYY-MM-DDTHH：mm：ss。FFF±hh：mm 格式。
Duration	使用持续时间作为参数输入值，使用 [-]P（n）DT（n）H（n）M（n）S 格式。例如：P3DT4H30M10S（3 天、4 小时、30 分钟和 10 秒）。
Number	使用数字作为参数输入值（整数或浮点）。
Text	使用文本作为参数输入值。
Time	使用 HH：mm：ss 将时间用作参数输入值。FFFZ 格式。

ErrorRelatedResource

Object

与错误相关的资源详细信息对象。

名称	类型	说明
resourceId	string	错误中涉及的资源 ID。
resourceType	string	错误中涉及的资源的类型。

ErrorResponse

Object

错误响应。

名称	类型	说明
errorCode	string	提供有关错误条件的信息的特定标识符，允许服务与其用户之间的标准化通信。
message	string	错误的人工可读表示形式。
moreDetails	ErrorResponseDetails[]	其他错误详细信息的列表。
relatedResource	ErrorRelatedResource	与错误相关的资源详细信息。
requestId	string	与错误关联的请求的 ID。

ErrorResponseDetails

Object

错误响应详细信息。

名称	类型	说明
errorCode	string	提供有关错误条件的信息的特定标识符，允许服务与其用户之间的标准化通信。
message	string	错误的人工可读表示形式。
relatedResource	ErrorRelatedResource	与错误相关的资源详细信息。

KeyCredentials

Object

Key CredentialType 的凭据。

名称	类型	说明
credentialType	string: Key	连接的凭据类型。
key	string	键。

ListConnectionDetails

Object

列表作的连接详细信息输出。

名称	类型	说明
path	string	连接的路径。
type	string	连接的类型。

ListCredentialDetails

Object

提取连接时返回的凭据详细信息。

名称	类型	说明
connectionEncryption	ConnectionEncryption	测试连接期间使用的连接加密设置。
credentialType	CredentialType	连接的凭据类型。
singleSignOnType	SingleSignOnType	连接的单一登录类型。
skipTestConnection	boolean	连接是否应在创建和更新期间跳过测试连接。 True - 跳过测试连接，False - 请勿跳过测试连接。

OnPremisesCredentialEntry

Object

网关 ID 及其加密的序列化凭据。

名称	类型	说明
encryptedCredentials	string	名称值对列表的加密序列化 .json。名称是凭据名称，值为凭据值。使用具有本地网关成员公钥的 Rivest-Shamir-Adleman （RSA）加密算法执行加密。
gatewayId	string uuid	网关的对象 ID。

OnPremisesGatewayCredentials

Object

用于通过本地网关进行身份验证的凭据。

名称	类型	说明
credentialType	CredentialType	连接的凭据类型。
values	OnPremisesCredentialEntry[]	要发送到本地网关的凭据有效负载。

PrivacyLevel

Enumeration

连接的隐私级别设置。可能会随着时间的推移添加其他隐私级别。

值	说明
None	未配置隐私级别设置。
Organizational	设置为组织的连接可以折叠到专用和其他组织连接。它们无法折叠到公共连接。可见性设置为受信任的组。
Private	设置为专用的连接包含敏感或机密信息。可见性可以限制为授权用户。专用连接中的数据不会折叠到其他连接，包括其他专用连接。
Public	可以将文件、Internet 连接和工作簿数据设置为公共数据。数据可以折叠到其他连接。可见性可供所有人使用。

ServicePrincipalCredentials

Object

ServicePrincipal CredentialType 的凭据。

名称	类型	说明
credentialType	string: ServicePrincipal	连接的凭据类型。
servicePrincipalClientId	string uuid	服务主体的客户端 ID。
servicePrincipalSecret	string	服务主体的机密。
tenantId	string uuid	服务主体的租户 ID。

SharedAccessSignatureCredentials

Object

SharedAccessSignature CredentialType 的凭据。

名称	类型	说明
credentialType	string: SharedAccessSignature	连接的凭据类型。
token	string	令牌。

SingleSignOnType

Enumeration

连接的单一登录类型。可能会随着时间的推移添加其他单一登录类型。

值	说明
Kerberos	连接使用 Kerberos 单一登录进行连接。
KerberosDirectQueryAndRefresh	连接使用 Kerberos DirectQuery 和 Refresh 单一登录进行连接。
MicrosoftEntraID	连接使用 Microsoft Entra ID 单一登录进行连接。
None	连接不使用单一登录进行连接。
SecurityAssertionMarkupLanguage	连接使用安全断言标记语言（SAML）单一登录进行连接。

WindowsCredentials

Object

Windows CredentialType 的凭据。

名称	类型	说明
credentialType	string: Windows	连接的凭据类型。
password	string	密码。
username	string	用户名。

WindowsWithoutImpersonationCredentials

Object

WindowsWithoutImpersonation CredentialType 的凭据。

名称	类型	说明
credentialType	string: WindowsWithoutImpersonation	连接的凭据类型。

WorkspaceIdentityCredentials

Object

WorkspaceIdentity CredentialType 的凭据。

名称	类型	说明
credentialType	string: WorkspaceIdentity	连接的凭据类型。

通过

Connections - Create Connection

权限

所需的委派范围

Microsoft Entra 支持的标识

接口

请求正文

CreateCloudConnectionRequest

CreateOnPremisesConnectionRequest

CreateVirtualNetworkGatewayConnectionRequest

响应

示例

Cloud example

示例请求

示例响应

Virtual network gateway example

示例请求

示例响应

定义

AnonymousCredentials

BasicCredentials

Connection

ConnectionDetailsBooleanParameter

ConnectionDetailsDateParameter

ConnectionDetailsDateTimeParameter

ConnectionDetailsDateTimeZoneParameter

ConnectionDetailsDurationParameter

ConnectionDetailsNumberParameter

ConnectionDetailsTextParameter

ConnectionDetailsTimeParameter

ConnectionEncryption

ConnectivityType

CreateCloudConnectionRequest

CreateConnectionDetails

CreateCredentialDetails

CreateOnPremisesConnectionRequest

CreateOnPremisesCredentialDetails

CreateVirtualNetworkGatewayConnectionRequest

CredentialType

DataType

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

KeyCredentials

ListConnectionDetails

ListCredentialDetails

OnPremisesCredentialEntry

OnPremisesGatewayCredentials

PrivacyLevel

ServicePrincipalCredentials

SharedAccessSignatureCredentials

SingleSignOnType

WindowsCredentials

WindowsWithoutImpersonationCredentials

WorkspaceIdentityCredentials

其他资源