Pontos de extremidade do DCM.E
Pontos de extremidade do DCM.E e parâmetros
Os pontos de extremidade do DCM.E são divididos em dois grupos: pontos de extremidade do DCM.E para usuários e pontos de extremidade do DCM.E para administradores . Todos os pontos de extremidade do DCM.E exigem que o TLS seja configurado no Server.
Para saber mais sobre as relações de objetos e como usá-las na API, vá para a seção Relações de objetos .
Para obter mais informações sobre conexões de dados, visite as páginas de ajuda DCM – Server e Gerenciador de Conexões de Dados: IU do Server .
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
.
Pontos de extremidade do DCM.E para usuários
Esses pontos de extremidade podem ser usados por usuários com acesso à API:
Nota
All API endpoints return individual user data (each user can only see and manage their own connections).
All examples are in PowerShell.
Recuperar um registro de conexão do DCM
Para recuperar um registro de conexão do DCM, use o ponto de extremidade GET {baseURL}/v3/dcm/connections/{id} . O ponto de extremidade retorna todas as informações sobre a conexão do DCM, incluindo a fonte de dados e as credenciais relacionadas, bem como as informações de compartilhamento.
Parâmetros
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'
Recuperar uma conexão do DCM como referenciada em fluxos de trabalho
Para recuperar um registro de conexão do DCM como ela é referenciada em fluxos de trabalho, use o ponto de extremidade GET {baseURL}/v3/dcm/connections/lookup . O ponto de extremidade retorna todas as informações sobre a conexão do DCM, incluindo a fonte de dados e as credenciais relacionadas, bem como as informações de compartilhamento.
Nota
O ConnectionID usado nesse ponto de extremidade é diferente do ID usado em outros pontos de extremidade do DCM. O ID é usado para referenciar vários objetos do DCM, enquanto o ConnectionID é usado apenas em fluxos de trabalho para referenciar a conexão do DCM para usuários específicos.
Parâmetros
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'
Compartilhar uma conexão do DCM com usuários e grupos especificados
Para compartilhar uma conexão do DCM para execução do Server com usuários ou grupos especificados, use o ponto de extremidade PUT {baseURL}/v3/dcm/connections/{id}/sharing/execution .
Nota
Como esse é um ponto de extremidade PUT, ele substitui o compartilhamento existente em vez de adicionar usuários ou grupos de usuários adicionais à lista existente. A lista fornecida de usuários e grupos não pode estar vazia; para remover o compartilhamento existente, use o ponto de extremidade DELETE.
Parâmetros
id (cadeia de caracteres): obrigatório. Insira o ID da conexão do DCM que deseja compartilhar com outros usuários ou grupos.
sharingContract (corpo): obrigatório. Para atualizar o compartilhamento de execução, o parâmetro "sharingContract" é obrigatório. Ambas as matrizes são obrigatórias, e apenas uma pode ser deixada vazia.
userIds (matriz de cadeia de caracteres): insira uma lista de todos os IDs do usuário com quem a conexão será compartilhada. Deixe uma matriz vazia se não houver usuários com quem compartilhar (somente userGroups).
userGroupIds (matriz de cadeia de caracteres): insira uma lista de todos os IDs do grupo de usuários com quem a conexão será compartilhada. Deixe uma matriz vazia se não houver grupos de usuários com quem compartilhar (somente usuários).
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" ] }'
Reverter o compartilhamento de uma conexão do DCM
Para reverter o compartilhamento de uma conexão do DCM, use o ponto de extremidade DELETE {baseURL}/v3/dcm/connections/{id}/sharing/execution .
Parâmetros
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'
Criar ou atualizar uma conexão do DCM
Para criar ou atualizar uma conexão do DCM, use o ponto de extremidade POST {baseURL}/v3/dcm/connections .
O ponto de extremidade único serve funções de criação e atualização, diferenciadas pela existência de IDs de objeto incluídos na solicitação. A reutilização de fontes de dados ou credenciais existentes não é atualmente compatível ao criar novas conexões.
Parâmetros
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.
Nota
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.
Nota
There are several different
parameters
objects 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
schemaName
defined in that part of the connection. They are independent and can (and often do) contain different fields.The
parameters
property 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
parameters
object in the response.
This is the most reliable way to discover the required and available fields for your specific data source or credential.
Because
parameters
fields 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.schemaName
property.parameters (object): Required. Parameters for the
DataSource
part of the connection. SeeConnection.parameters
property 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. Theobject
has 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
oauthApplication
andoauthTokens <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
Credential
parts of the connection. SeeConnection.parameters
property 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": {} } } } }'
Excluir uma conexão do DCM
Para excluir uma conexão do DCM, use o ponto de extremidade DELETE {baseURL}/v3/dcm/connections/{id} . A fonte de dados e as credenciais também serão excluídas, a menos que sejam usadas em qualquer outra conexão.
Parâmetros
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'
Pontos de extremidade do DCM.E para administradores
Pontos de extremidade que podem ser usados por administradores com acesso à API:
Nota
All admin API endpoints return all data available on the Server across all users, regardless of ownership.
All examples are in PowerShell.
Recuperar um registro de conexão do DCM
Para recuperar um registro de conexão do DCM, use o ponto de extremidade GET {baseURL}/v3/dcm/admin/connections/{objectId} .
Parâmetros
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'
Recuperar uma lista de registros de conexões do DCM
Para recuperar uma lista de todos os registros de conexões do DCM presentes no Server, use o ponto de extremidade GET {baseURL}/v3/dcm/admin/connections .
Parâmetros
Ambos os parâmetros são filtros que podem ser combinados. Usar connectionId e visibleBy juntos retornará a conexão com o ConnectionID especificado, visível pelo usuário especificado.
connectionId (cadeia de caracteres): opcional. Filtra as conexões por seu connectionID, como referenciadas a partir de um fluxo de trabalho. Várias conexões poderão ser retornadas para um único connectionID, se a conexão for compartilhada para colaboração.
visibleBy (cadeia de caracteres): opcional. Insira o ID do usuário. Se presente, filtra os resultados para o mesmo resultado de todas as conexões disponíveis para o usuário especificado.
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3&visibleBy=bc7cb7b47c33' ` --header 'Authorization: Bearer BearerTokenGoesHere'
Criar ou atualizar uma conexão do DCM em nome do usuário
Para criar ou atualizar um registro de conexão do DCM em nome de um usuário, use o ponto de extremidade 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": {} } } } } } } }'
Reverter o compartilhamento de uma conexão do DCM compartilhada para execução
Para reverter o compartilhamento de uma conexão do DCM cujo tipo de compartilhamento foi definido como "Compartilhada para execução", use o ponto de extremidade DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/execution endpoint.
Parâmetros
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'
Reverter o compartilhamento de uma conexão do DCM compartilhada para colaboração
Para reverter o compartilhamento de uma conexão do DCM cujo tipo de compartilhamento foi definido como "Compartilhada para colaboração", use o ponto de extremidade DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/collaboration .
Parâmetros
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'
Excluir uma conexão do DCM
Para excluir um registro de conexão do DCM, use o ponto de extremidade DELETE {baseURL}/v3/dcm/admin/connections/{objectId} . A fonte de dados e as credenciais também serão excluídas, a menos que sejam usadas em qualquer outra conexão.
Parâmetros
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'
Get All Connection Handling Rules
To get all Connection handling rules, use the GET {baseURL}/v3/dcm/admin/connectionhandlingrules endpoint.
Go to DCM Connection Handling for more information.
Properties
No properties.
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules' ` --header 'Authorization: Bearer BearerTokenGoesHere'
Get Connection Handling Rule
To get a specific DCM Connection handling rule, use the GET {baseURL}/v3/dcm/admin/connectionhandlingrules/{id} endpoint.
Properties
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'
Add or Update Connection Handling Rule
To add a new Connection handling rule or update an existing one, use the POST {baseURL}/v3/dcm/admin/connectionhandlingrules endpoint.
Properties
Insira os seguintes parâmetros para criar ou atualizar uma regra de tratamento de conexão do DCM:
rule (corpo): obrigatório. A "ConnectionHandlingRule" do DCM para criar ou atualizar.
id (cadeia de caracteres): opcional. O ID da regra de tratamento de conexão do DCM. Insira o ID da regra de tratamento de conexão do DCM se desejar atualizar regra de tratamento de conexão existente. Ignore se desejar criar uma nova regra de tratamento de conexão.
sourceConnectionId (cadeia de caracteres): insira um "sourceConnectionId", fazendo referência a um "ConnectionId" a ser substituído na execução do fluxo de trabalho. A conexão não precisa existir no Server (fluxos de trabalho que façam referência a ela ainda podem ser executados). Ela não pode ser usada em nenhuma outra regra existente, seja como conexão de origem ou de destino.
sourceConnectionTitle (cadeia de caracteres): insira um nome personalizado ou descrição da conexão de origem.
targetConnectionId (cadeia de caracteres): insira um "targetConnectionId". Deve fazer referência a uma conexão do DCM presente no Server.
targetConnectionTitle (cadeia de caracteres): insira um nome personalizado ou descrição da conexão de destino.
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" }'
Delete Connection Handling Rule
To delete an existing Connection handling rule, use the DELETE {baseURL}/v3/dcm/admin/connectionhandlingrules/{id} endpoint.
Properties
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'
Relações de objetos
Se estiver criando uma conexão do DCM, você poderá usar objetos criados da seguinte maneira:
Objeto criado:
" id " (por exemplo, "id": "c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3")
“ connectionId ” (por exemplo, "id": "c0332423423-86cc-4e7e-93a3-d500cca9a3f3")
Você pode usá-lo como:
id se você desejar recuperar um registro de conexão do DCM
connectionId se você desejar recuperar uma conexão do DCM como referenciada em fluxos de trabalho
id se você desejar compartilhar uma conexão do DCM com usuários e grupos especificados
id se você desejar atualizar uma conexão do DCM
id se você desejar excluir uma conexão do DCM
id se você desejar reverter o compartilhamento de uma conexão do DCM
Administrador :
id se você desejar recuperar um registro de conexão do DCM
ownerId (userId) se você desejar criar uma conexão do DCM em nome de um usuário
id se você desejar atualizar uma conexão do DCM em nome de um usuário
id se você desejar reverter o compartilhamento de uma conexão do DCM compartilhada para execução
id se você desejar reverter o compartilhamento de uma conexão do DCM compartilhada para colaboração
id se você desejar excluir uma conexão do DCM