Connections - Update Connection

参考

服务:: Core

API 版本:: v1

按 ID 更新连接。
若要加密凭据，请参阅以编程方式配置凭据。

权限

调用方必须具有连接网关的连接权限或管理员权限。

所需的委派范围

Connection.ReadWrite.All

Microsoft Entra 支持的标识

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

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

接口

PATCH https://api.fabric.microsoft.com/v1/connections/{connectionId}

URI 参数

名称	在	必需	类型	说明
connectionId	path	True	string (uuid)	连接的 ID。

请求正文

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

名称	说明
UpdateOnPremisesGatewayConnectionRequest
UpdateOnPremisesGatewayPersonalConnectionRequest
UpdatePersonalCloudConnectionRequest
UpdateShareableCloudConnectionRequest
UpdateVirtualNetworkGatewayConnectionRequest

UpdateOnPremisesGatewayConnectionRequest

名称	必需	类型	说明
connectivityType	True	string: OnPremisesGateway	连接的连接类型。
credentialDetails		UpdateOnPremisesGatewayCredentialDetails	连接的凭据详细信息。
displayName		string	连接的显示名称。最大长度为 200 个字符。
privacyLevel		PrivacyLevel	连接的隐私级别。

UpdateOnPremisesGatewayPersonalConnectionRequest

名称	必需	类型	说明
connectivityType	True	string: OnPremisesGatewayPersonal	连接的连接类型。
credentialDetails		UpdateOnPremisesGatewayPersonalCredentialDetails	连接的凭据详细信息。
privacyLevel		PrivacyLevel	连接的隐私级别。

UpdatePersonalCloudConnectionRequest

名称	必需	类型	说明
connectivityType	True	string: PersonalCloud	连接的连接类型。
credentialDetails		UpdateCredentialDetails	连接的凭据详细信息。
privacyLevel		PrivacyLevel	连接的隐私级别。

UpdateShareableCloudConnectionRequest

名称	必需	类型	说明
connectivityType	True	string: ShareableCloud	连接的连接类型。
credentialDetails		UpdateCredentialDetails	连接的凭据详细信息。
displayName		string	连接的显示名称。最大长度为 200 个字符。
privacyLevel		PrivacyLevel	连接的隐私级别。

UpdateVirtualNetworkGatewayConnectionRequest

名称	必需	类型	说明
connectivityType	True	string: VirtualNetworkGateway	连接的连接类型。
credentialDetails		UpdateCredentialDetails	连接的凭据详细信息。
displayName		string	连接的显示名称。最大长度为 200 个字符。
privacyLevel		PrivacyLevel	连接的隐私级别。

响应

名称	类型	说明
200 OK	Connection	还行。作成功。
Other Status Codes	ErrorResponse	常见错误代码： EntityNotFound - 找不到请求的资源。 InsufficientPermissionsToManageConnection - 调用方没有足够的权限来管理此连接。 DuplicateConnectionName - 连接名称已在使用中。 IncorrectCredentials - 无法使用凭据输入建立连接。 UpdateGatewayConnectionFailed - 无法更新网关连接。

名称

类型

说明

200 OK

Connection

还行。作成功。

Other Status Codes

ErrorResponse

常见错误代码：

EntityNotFound - 找不到请求的资源。
InsufficientPermissionsToManageConnection - 调用方没有足够的权限来管理此连接。
DuplicateConnectionName - 连接名称已在使用中。
IncorrectCredentials - 无法使用凭据输入建立连接。
UpdateGatewayConnectionFailed - 无法更新网关连接。

示例

On-premises gateway (personal mode) example

On-premises gateway example

Personal cloud example

Shareable cloud example

Virtual network gateway example

On-premises gateway (personal mode) example

示例请求

HTTP

PATCH https://api.fabric.microsoft.com/v1/connections/ef8f408d-2ab7-4a18-b662-9251febda49c

{
  "connectivityType": "OnPremisesGatewayPersonal",
  "credentialDetails": {
    "credentials": {
      "credentialType": "WindowsWithoutImpersonation",
      "encryptedCredentials": "************************************"
    }
  }
}

示例响应

状态代码:: 200

{
  "id": "ef8f408d-2ab7-4a18-b662-9251febda49c",
  "gatewayId": "429a773e-5633-45ee-8584-a192bd79c16a",
  "connectivityType": "OnPremisesGatewayPersonal",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;reporting"
  },
  "privacyLevel": "Private",
  "credentialDetails": {
    "credentialType": "WindowsWithoutImpersonation",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

On-premises gateway example

示例请求

HTTP

PATCH https://api.fabric.microsoft.com/v1/connections/70b17680-48f1-4729-9df6-02576647dc3a

{
  "connectivityType": "OnPremisesGateway",
  "displayName": "ContosoSalesOnPremisesConnection",
  "credentialDetails": {
    "skipTestConnection": false,
    "credentials": {
      "credentialType": "Windows",
      "values": [
        {
          "gatewayId": "4f8b5d6e-8e99-4817-8b9e-6b6a613be707",
          "encryptedCredentials": "************************************"
        },
        {
          "gatewayId": "c6961028-1309-4183-9799-a0b0fa28a235",
          "encryptedCredentials": "************************************"
        }
      ]
    }
  }
}

示例响应

状态代码:: 200

{
  "id": "70b17680-48f1-4729-9df6-02576647dc3a",
  "displayName": "ContosoSalesOnPremisesConnection",
  "gatewayId": "4f8b5d6e-8e99-4817-8b9e-6b6a613be707",
  "connectivityType": "OnPremisesGateway",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;sales"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Windows",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

Personal cloud example

示例请求

HTTP

PATCH https://api.fabric.microsoft.com/v1/connections/7a0369b2-58c4-4b67-b3f3-92156a95f1cd

{
  "connectivityType": "PersonalCloud",
  "privacyLevel": "Organizational"
}

示例响应

状态代码:: 200

{
  "id": "7a0369b2-58c4-4b67-b3f3-92156a95f1cd",
  "connectivityType": "PersonalCloud",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;finances"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "OAuth2",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

Shareable cloud example

示例请求

HTTP

PATCH https://api.fabric.microsoft.com/v1/connections/fa968eee-8075-48f6-8c6d-41260ee1396d

{
  "connectivityType": "ShareableCloud",
  "displayName": "ContosoCloudConnection"
}

示例响应

状态代码:: 200

{
  "id": "fa968eee-8075-48f6-8c6d-41260ee1396d",
  "displayName": "ContosoCloudConnection",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;networks"
  },
  "privacyLevel": "Public",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": true
  }
}

Virtual network gateway example

示例请求

HTTP

PATCH https://api.fabric.microsoft.com/v1/connections/6b571614-2e98-4bfd-b9ed-1cb8d3ffc396

{
  "connectivityType": "VirtualNetworkGateway",
  "displayName": "ContosoMarketingVirtualNetworkGatewayConnection",
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "singleSignOnType": "None"
  }
}

示例响应

状态代码:: 200

{
  "id": "6b571614-2e98-4bfd-b9ed-1cb8d3ffc396",
  "displayName": "ContosoMarketingVirtualNetworkGatewayConnection",
  "gatewayId": "befccff4-3ee6-40d7-b8f1-a0a9fd684a85",
  "connectivityType": "VirtualNetworkGateway",
  "connectionDetails": {
    "type": "SQL",
    "path": "contoso.database.windows.net;marketing"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "Basic",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

定义

名称	说明
AnonymousCredentials	匿名 CredentialType 的凭据。
BasicCredentials	Basic CredentialType 的凭据。
Connection
ConnectionEncryption	连接的连接加密类型。可能会随着时间的推移添加其他连接加密值。
ConnectivityType	连接的连接类型。可能会随着时间的推移添加其他连接类型。
CredentialType	连接的凭据类型。可能会随着时间的推移添加其他凭据类型。
ErrorRelatedResource	与错误相关的资源详细信息对象。
ErrorResponse	错误响应。
ErrorResponseDetails	错误响应详细信息。
KeyCredentials	Key CredentialType 的凭据。
ListConnectionDetails	列表作的连接详细信息输出。
ListCredentialDetails	提取连接时返回的凭据详细信息。
OnPremisesCredentialEntry	网关 ID 及其加密的序列化凭据。
OnPremisesGatewayCredentials	用于通过本地网关进行身份验证的凭据。
OnPremisesGatewayPersonalCredentials	用于通过本地网关（个人模式）进行身份验证的凭据。
PrivacyLevel	连接的隐私级别设置。可能会随着时间的推移添加其他隐私级别。
ServicePrincipalCredentials	ServicePrincipal CredentialType 的凭据。
SharedAccessSignatureCredentials	SharedAccessSignature CredentialType 的凭据。
SingleSignOnType	连接的单一登录类型。可能会随着时间的推移添加其他单一登录类型。
UpdateCredentialDetails	用于更新连接的凭据详细信息输入。
UpdateOnPremisesGatewayConnectionRequest
UpdateOnPremisesGatewayCredentialDetails	用于更新本地网关连接的凭据详细信息输入。
UpdateOnPremisesGatewayPersonalConnectionRequest
UpdateOnPremisesGatewayPersonalCredentialDetails	用于更新本地网关连接的凭据详细信息输入。
UpdatePersonalCloudConnectionRequest
UpdateShareableCloudConnectionRequest
UpdateVirtualNetworkGatewayConnectionRequest
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	连接的隐私级别。

ConnectionEncryption

枚举

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

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

ConnectivityType

枚举

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

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

CredentialType

枚举

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

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

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[]	要发送到本地网关的凭据有效负载。

OnPremisesGatewayPersonalCredentials

Object

用于通过本地网关（个人模式）进行身份验证的凭据。

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

PrivacyLevel

枚举

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

值	说明
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

枚举

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

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

UpdateCredentialDetails

Object

用于更新连接的凭据详细信息输入。

名称	类型	说明
connectionEncryption	ConnectionEncryption	测试连接期间使用的连接加密设置。
credentials	Credentials: AnonymousCredentials BasicCredentials KeyCredentials ServicePrincipalCredentials SharedAccessSignatureCredentials WindowsCredentials WindowsWithoutImpersonationCredentials WorkspaceIdentityCredentials	连接的凭据。
singleSignOnType	SingleSignOnType	连接的单一登录类型。
skipTestConnection	boolean	连接是否应在创建和更新期间跳过测试连接。 True - 跳过测试连接，False - 请勿跳过测试连接。

UpdateOnPremisesGatewayConnectionRequest

Object

名称	类型	说明
connectivityType	string: OnPremisesGateway	连接的连接类型。
credentialDetails	UpdateOnPremisesGatewayCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。最大长度为 200 个字符。
privacyLevel	PrivacyLevel	连接的隐私级别。

UpdateOnPremisesGatewayCredentialDetails

Object

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

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

UpdateOnPremisesGatewayPersonalConnectionRequest

Object

名称	类型	说明
connectivityType	string: OnPremisesGatewayPersonal	连接的连接类型。
credentialDetails	UpdateOnPremisesGatewayPersonalCredentialDetails	连接的凭据详细信息。
privacyLevel	PrivacyLevel	连接的隐私级别。

UpdateOnPremisesGatewayPersonalCredentialDetails

Object

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

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

UpdatePersonalCloudConnectionRequest

Object

名称	类型	说明
connectivityType	string: PersonalCloud	连接的连接类型。
credentialDetails	UpdateCredentialDetails	连接的凭据详细信息。
privacyLevel	PrivacyLevel	连接的隐私级别。

UpdateShareableCloudConnectionRequest

Object

名称	类型	说明
connectivityType	string: ShareableCloud	连接的连接类型。
credentialDetails	UpdateCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。最大长度为 200 个字符。
privacyLevel	PrivacyLevel	连接的隐私级别。

UpdateVirtualNetworkGatewayConnectionRequest

Object

名称	类型	说明
connectivityType	string: VirtualNetworkGateway	连接的连接类型。
credentialDetails	UpdateCredentialDetails	连接的凭据详细信息。
displayName	string	连接的显示名称。最大长度为 200 个字符。
privacyLevel	PrivacyLevel	连接的隐私级别。

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	连接的凭据类型。