DCME 端点
DCME 端点和参数
DCME 端点分为两组：面向用户的 DCME 端点和面向管理员的 DCME 端点。所有 DCME 端点都要求在 Server 上配置 TLS。
要详细了解对象关系以及如何在 API 中使用对象关系，请参阅对象关系部分。
如需详细了解数据连接，请访问 DCM - Server 和数据连接管理器：Server UI 帮助页面。
What Is a DCM Connection?
“DCM Connection” is composed from its own parameters and two types of subobjects: DataSource (there is always just one) and Credentials (in common scenarios there are zero, one or two credentials but in rare cases there could be even more, the number is connector-specific). Each Credential has a different credRole inside the Connection. DCM API works on Connections as whole objects including DataSource and Credentials.
面向用户的 DCME 端点
具有 API 访问权限的用户可以使用这些端点：
注意
All API endpoints return individual user data (each user can only see and manage their own connections).
All examples are in PowerShell.
检索 DCM 连接记录
要检索 DCM 连接记录，请使用 GET {baseURL}/v3/dcm/connections/{id} 端点。端点会返回有关 DCM 连接的所有信息，包括相关数据源和凭证以及共享信息。
参数
id (string): Required. Enter the ID of the DCM Connection on which you want to obtain information.
curl --location --request GET 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' ` --header 'Authorization: Bearer BearerTokenGoesHere'
检索工作流中引用的 DCM 连接
要检索工作流中引用的 DCM 连接记录，请使用 GET {baseURL}/v3/dcm/connections/lookup 端点。端点会返回有关 DCM 连接的所有信息，包括相关数据源和凭证以及共享信息。
注意
此端点中使用的 ConnectionID 与其他 DCM 端点中使用的 ID 不同。ID 用于引用各种 DCM 对象，而 ConnectionID 仅在工作流中用于引用特定用户的 DCM 连接。
参数
connectionId (string): Required. Enter the DCM ConnectionID on which you want to obtain information.
curl --location --request GET 'https://localhost/webapi/v3/dcm/connections/lookup?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' ` --header 'Authorization: Bearer BearerTokenGoesHere'
与指定用户和用户组共享 DCM 连接
要与指定的用户或用户组共享 DCM 连接以便执行 Server 任务，请使用 PUT {baseURL}/v3/dcm/connections/{id}/sharing/execution 端点。
注意
由于这是一个 PUT 端点，因此它会覆盖现有的共享，而不是向现有列表添加其他用户或用户组。提供的用户和用户组列表不能为空；要移除现有共享，请使用 DELETE 端点。
参数
id (string)：必填。输入要与其他用户或用户组共享的 DCM 连接 ID。
sharingContract (body)：必填。要更新执行共享，必须指定 sharingContract 参数。两个数组都是必需的，但只有一个数组可以留空。
userIds (string array)：输入要与其共享连接的所有用户 ID 的列表。如果没有用户可以共享，则保留空数组（仅限 userGroups）。
userGroupIds (string array)：输入要与其共享连接的所有用户组 ID 的列表。如果没有用户组可以共享，则保留空数组（仅限 users）。
curl --location --request PUT 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/execution' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--header 'Content-Type: application/json' `
--data '{
"userIds": [
"61d57bea3c15317e1a48205b",
"61d564361d6d5da7ad461a32"
],
"userGroupIds": [
"d5da7ad4"
]
}'取消共享 DCM 连接
要取消共享 DCM 连接，请使用 DELETE {baseURL}/v3/dcm/connections/{id}/sharing/execution 端点。
参数
id (string): Required. Enter the DCM Connection ID you want to unshare from all users and groups.
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/execution' ` --header 'Authorization: Bearer BearerTokenGoesHere'
创建或更新 DCM 连接
要创建或更新 DCM 连接，请使用 POST {baseURL}/v3/dcm/connections 端点。
单个端点同时提供创建和更新功能，根据请求中是否包含对象 ID 进行区分。目前不支持在创建新连接时重复使用现有数据源或凭证。
参数
id (string): Optional. Enter a connection ID if you wish to update an existing connection. Skip if you wish to create a new connection.
name (string): Required. Enter the name of your connection.
注意
There are multiple “names” inside a DCM Connection:
Connection.name: The name of the Connection itself. Admins interact with this name via the API.Connection.dataSource.object.name: Data Source name visible on the Data Sources tab in the UI.Connection.credentials.<credRole>.object.name: Credential names visible on the Credentials tab in the UI.
For more details, see the What is a DCM Connection? section.
schemaName (string): Required. This is the identifier for a DCM schema, which is used to render and validate the associated parameters in the DCM UI. Each connector defines its own set of supported DCM schemas. The selected connection schema also specifies which DataSource and Credential schemas must be used for the DataSource and Credential sections of the connection. For more details, see What is a DCM Connection? and How is a Connector Related to a DCM Connection?
allowInSdks (boolean): Optional. Makes the Connection accessible to python SDK tools.
parameters (object): Required. This property holds configuration details specific to the schema and technology you are connecting to.
注意
There are several different
parametersobjects in a DCM connection structure, each used in a different context:Connection.parameters: for the overall connection (not yet visible in UI, coming soon)Connection.dataSource.object.parameters: for the Data Source part of the connectionConnection.credentials.<credRole>.object.parameters: for each Credential roleConnection.credentials.<credRole>.object.secrets.<secretType>.parameters: for credential secrets, per secret type
Each parameters object has its own structure and required fields, which depend on the technology and
schemaNamedefined in that part of the connection. They are independent and can (and often do) contain different fields.The
parametersproperty is required but may be provided as empty objects ({}) if no parameters are needed for a given schema.Tip:
To determine the correct fields for any parameters object:
Create a DCM Connection in the Alteryx Server UI for your target technology.
Query the Connection via API:
GET /v3/dcm/connections/{id}Review the structure and fields returned for each
parametersobject in the response.
This is the most reliable way to discover the required and available fields for your specific data source or credential.
Because
parametersfields are data source and credential specific, a comprehensive example for every technology isn’t practical in this documentation. Please use the above workflow to get up-to-date, source-specific examples.dataSource (object): Required. The data source used for the connection, describing the data source instance host and additional parameters, as seen in DCM UI.
object (object): Required.
id (string): Enter a data source ID if you wish to update an existing connection. Skip if you wish to create a new connection. Using an existing data source when creating new connections is currently unavailable.
name (string): Required. Enter a name for the data source.
schemaName (string): Required. Enter the schema name of the selected data source. For a detailed description, refer to the
Connection.schemaNameproperty.parameters (object): Required. Parameters for the
DataSourcepart of the connection. SeeConnection.parametersproperty for more details. Provide empty object{}if no parameters are needed.
credentials (object): Required. Key value pairs of
<credRole>: object.<credRole>s are defined by the selected DCM schema. Theobjecthas just one property named“object"which then contains all the Credential properties. Some connections may not require any credentials, while others may have multiple nested Credential objects.From the examples below, you can see that the SQLServer (MSSQL) Username-Password authentication uses main <credRole>. Reshift connection with Identity Pool authentication and Snowflake with OAuth authentication use
oauthApplicationandoauthTokens <credRoles>for their credentials.For more details, see What is a DCM Connection? and How is a Connector related to DCM Connection?
object (object): Defines properties of Credential parts of the Connection.
id (string): Enter a credential ID if you wish to update an existing connection. Skip if you wish to create a new connection. Using an existing credential when creating new connections is currently unavailable.
name (string): Required. Enter the name of your credential.
schemaName (string): Required. Enter the schema name of the selected credential.
parameters (object): Required. Parameters for the
Credentialparts of the connection. SeeConnection.parametersproperty for more details. Provide empty object{}if no parameters are needed.
Create a SQL Server DCM Connection Using UserName-Password Credentials
curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--header 'Content-Type: application/json' `
--data '{
"name": "MSSQL DEV Admin",
"schemaName": "database-odbc-dsn-mssql",
"parameters": {},
"dataSource": {
"object": {
"name": "SQL Server DEV",
"schemaName": "database-odbc-dsn-mssql",
"parameters": {
"dsn": "sql server"
}
}
},
"credentials": {
"main": {
"object": {
"name": "SQL Server Admin Credentials",
"schemaName": "username_password",
"parameters": {},
"userName": "admin",
"secrets": {
"password": {
"value": {
"text": "password"
},
"parameters": {}
}
}
}
}
}
}'
Create an ODBC DCM Connection to Redshift Using OAuth Authentication with AWS IAM / Cognito
curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--header 'Content-Type: application/json' `
--data '{
"name": "Connection Name",
"schemaName": "database-odbc-redshift-simba-oauth-iam-identitypool",
"allowInSdks": false,
"parameters": {},
"dataSource": {
"object": {
"name": "DataSource Name",
"schemaName": "database-odbc-redshift-simba",
"drvName": "Simba Amazon Redshift ODBC Driver",
"host": "##### (my-database-host.redshift.amazonaws.com)",
"parameters": {
"allowSelfSignedServerCert": false,
"checkCertRevocation": false,
"database": "#####",
"minTLS": 2,
"port": 5439,
"sslMmode": "require",
"useSystemTrustStore": false
}
}
},
"credentials": {
"oauthApplication": {
"object": {
"name": "Application Credential Name",
"schemaName": "database-redshift-aws-oauth-iam-identitypool-application",
"userName": "##### (Client Secret)",
"parameters": {
"accountId": "#####",
"authorityURL": "##### (https://my-authorization-host.amazoncognito.com)",
"awsRegion": "##### (us-west-2)",
"dbUser": "#####",
"identityPoolId": "#####",
"redirectURI": "##### (http://localhost:5634)",
"userPoolId": "#####"
},
"secrets": {
}
}
},
"oauthTokens": {
"object": {
"name": "Tokens Credential Name",
"schemaName": "aws-oauth-iam-identitypool-tokens",
"parameters": {},
"secrets": {
}
}
}
}
}'Create a Snowflake DCM Connection with OAuth 2.0 Client Credentials
curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--header 'Content-Type: application/json' `
--data '{
"name": "Connection Name",
"schemaName": "database-odbc-snowflake-simba-oauth-generic-configurable",
"allowInSdks": false,
"parameters": {},
"dataSource": {
"object": {
"name": "DataSource Name",
"schemaName": "database-odbc-snowflake-simba",
"drvName": "Simba Snowflake ODBC Driver",
"host": "##### (my-domain.snowflakecomputing.com)",
"parameters": {
"database": "#####",
"schema": "#####",
"warehouse": "#####"
}
}
},
"credentials": {
"oauthApplication": {
"object": {
"name": "Application Credential Name",
"schemaName": "generic-configurable-oauth-application",
"userName": "##### (Client Id)",
"parameters": {
"clientAuthentication": "body",
"grantType": "clientCredentials",
"tokenURL": "#####"
},
"secrets": {
"clientSecret": {
"expiresOn": null,
"parameters": {},
"value": {
"text": "##### (Client Secret)"
}
}
}
}
},
"oauthTokens": {
"object": {
"name": "Tokens Credential Name",
"schemaName": "generic-configurable-oauth-tokens",
"userName": null,
"parameters": {
"scope": "#####"
},
"secrets": {}
}
}
}
}'删除 DCM 连接
要删除 DCM 连接，请使用 DELETE {baseURL}/v3/dcm/connections/{id} 端点。数据源和凭证若未用于任何其他连接，则也将予以删除。
参数
id (string): Required. Enter the DCM Connection ID you want to delete.
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' ` --header 'Authorization: Bearer BearerTokenGoesHere'
面向管理员的 DCME 端点
具有 API 访问权限的管理员可以使用的端点：
注意
All admin API endpoints return all data available on the Server across all users, regardless of ownership.
All examples are in PowerShell.
检索 DCM 连接记录
要检索 DCM 连接记录，请使用 GET {baseURL}/v3/dcm/admin/connections/{objectId} 端点。
参数
objectId (string): Required. Enter the DCM Connection ID you want to get information about.
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' ` --header 'Authorization: Bearer BearerTokenGoesHere'
检索 DCM 连接记录列表
要检索 Server 上存在的所有 DCM 连接记录的列表，请使用 GET {baseURL}/v3/dcm/admin/connections 端点。
参数
这两个参数都是可以组合的筛选条件。将 connectionId 和 visibleBy 一起使用将返回指定了 ConnectionID 的连接，该连接对指定用户可见。
connectionId (string)：可选。根据工作流引用的 connectionID 筛选连接。如果连接是为了协作而共享的，则可以为单个 connectionID 返回多个连接。
visibleBy (string)：可选。输入用户 ID。如果存在，它会将结果过滤为与指定用户可用的所有连接相同的结果。
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3&visibleBy=bc7cb7b47c33' ` --header 'Authorization: Bearer BearerTokenGoesHere'
代表用户创建或更新 DCM 连接
要代表用户创建或更新 DCM 连接记录，请使用 POST {baseURL}/v3/dcm/admin/connections 端点。
Properties
Use the same properties as described in the Create or Update Connection section. The only additional property required for this endpoint is ownerId.
ownerId (string): Required.
When creating a Connection, enter the ID of the user on behalf of which the connection shall be created.
When updating a Connection, you must also enter the ownerId even if you don't want to change it. For more information how to get an ownerID, go to Get Connection or List Connections.
curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--header 'Content-Type: application/json' `
--data '{
"upsertConnectionContract": {
"name": "MSSQL DEV Admin",
"ownerId": "1b4bc56d489d9543a",
"schemaName": "database-odbc-dsn-mssql",
"parameters": {},
"dataSource": {
"object": {
"name": "SQL Server DEV",
"schemaName": "database-odbc-dsn-mssql",
"parameters": {
"dsn": "sql server"
}
}
},
"credentials": {
"main": {
"object": {
"name": "SQL Server Admin Credentials",
"schemaName": "username_password",
"parameters": {},
"userName": "admin",
"secrets": {
"password": {
"value": {
"text": "password"
},
"parameters": {}
}
}
}
}
}
}
}'取消为执行而共享的 DCM 连接
要取消其共享类型已定义为“为执行而共享”的 DCM 连接，请使用 DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/execution 端点。
参数
objectId (string): Required. Enter the DCM Connection ID to be unshared for execution.
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/execution' ` --header 'Authorization: Bearer BearerTokenGoesHere'
取消为协作而共享的 DCM 连接
要取消其共享类型已定义为“为协作而共享”的 DCM 连接，请使用 DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/collaboration 端点。
参数
objectId (string): Required. Enter the DCM Connection ID to be unshared for collaboration.
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/collaboration' ` --header 'Authorization: Bearer BearerTokenGoesHere'
删除 DCM 连接
要删除 DCM 连接记录，请使用 DELETE {baseURL}/v3/dcm/admin/connections/{objectId} 端点。数据源和凭证若未用于任何其他连接，则也将予以删除。
参数
objectId (string): Required. Enter the DCM Connection ID you want to delete.
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' ` --header 'Authorization: Bearer BearerTokenGoesHere'
检索所有 DCM 连接处理规则
要检索所有 DCM 连接处理规则，请使用 GET {baseURL}/v3/dcm/admin/connectionhandlingrules 端点。
如需了解详情，请转到 DCM 连接处理。
参数
无参数。
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules' ` --header 'Authorization: Bearer BearerTokenGoesHere'
检索特定的 DCM 连接处理规则
要检索单个特定的 DCM 连接处理规则，请使用 GET {baseURL}/v3/dcm/admin/connectionhandlingrules/{id} 端点。
参数
id (string): Required. Specify the ID of the DCM connection handling rule to return.
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules/{id}' `
--header 'Authorization: Bearer BearerTokenGoesHere'添加或更新 DCM 连接处理规则
要添加新的 DCM 连接处理规则或更新现有规则，请使用 POST {baseURL}/v3/dcm/admin/connectionhandlingrules 端点。
参数
输入以下参数以创建或更新 DCM 连接处理规则：
rule (body)：必填。要创建或更新的 DCM 连接处理规则。
id (string)：可选。DCM 连接处理规则 ID。如果要更新现有连接处理规则，请输入 DCM 连接处理规则 ID。如果要创建新的连接处理规则，请跳过。
sourceConnectionId (string)：输入源连接 ID，引用执行工作流时要替换的连接 ID。此连接不必存在于 Server 上（仍然可以执行引用它的工作流）。此连接不能在另一个现有规则中使用，无论是作为源连接还是目标连接。
sourceConnectionTitle (string)：输入源连接的自定义名称或说明。
targetConnectionId (string)：输入目标连接 ID。必须引用 Server 上存在的 DCM 连接。
targetConnectionTitle (string)：输入目标连接的自定义名称或说明。
curl --location 'https://localhost.com/webapi/v3/dcm/admin/connectionhandlingrules' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--data '{
"sourceConnectionTitle": "MSSQL DEV",
"sourceConnectionId": "c.cid.d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3",
"targetConnectionId": "c.cid.cbf55382-f90b-4304-a1cd-37c5cff697e0"
}'删除现有 DCM 连接处理规则
要删除现有 DCM 连接处理规则，请使用 DELETE {baseURL}/v3/dcm/admin/connectionhandlingrules/{id} 端点。
参数
id (string): Required. Specify the DCM connection handling rule ID you want to delete.
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules/{id}' `
--header 'Authorization: Bearer BearerTokenGoesHere'对象关系
如果您要创建 DCM 连接，则可以按如下方式使用创建的对象：
创建的对象：
“id”（例如“id”: “c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3”）
“connectionId”（例如“id”: “c0332423423-86cc-4e7e-93a3-d500cca9a3f3”）
您可以将其用作：
id（如果要检索 DCM 连接记录）
connectionId（如果要检索工作流中引用的 DCM 连接）
id（如果要与指定用户和用户组共享 DCM 连接）
id（如果要更新 DCM 连接）
id（如果要删除 DCM 连接）
id（如果要取消共享 DCM 连接）
管理员：
id（如果要检索 DCM 连接记录）
ownerId (userId)（如果要代表用户创建 DCM 连接
id（如果要代表用户更新 DCM 连接）
id（如果要取消为执行而共享的 DCM 连接）
id（如果要取消为协作而共享的 DCM 连接）