Skip to main content

Puntos de conexión de DCME

Puntos de conexión y parámetros de DCME

Los puntos de conexión de DCME se dividen en dos grupos: puntos de conexión de DCME para usuarios y puntos de conexión de DCME para administradores. Todos los puntos de conexión de DCME requieren que se configure TLS en Server.

Para obtener más información sobre las relaciones entre objetos y cómo utilizarlas en la API, ve a la sección Relaciones entre objetos.

Para obtener más información sobre las conexiones de datos, visita las páginas de ayuda de DCM: Server y Administrador de conexiones de datos: interfaz de usuario de Server.DCM - ServerAdministrador de conexiones de datos: Interfaz de usuario de 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.

Puntos de conexión de DCME para usuarios

Estos puntos de conexión los pueden utilizar usuarios con acceso a 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 un registro de conexión de DCM

Para recuperar un registro de conexión de DCM, utiliza el punto de conexión GET {baseURL}/v3/dcm/connections/{id}. El punto de conexión devuelve toda la información sobre la conexión de DCM, incluidas la fuente de datos y las credenciales relacionadas, así como la información para compartir.

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 una conexión de DCM como se hace referencia en los flujos de trabajo

Para recuperar un registro de conexión de DCM tal como se hace referencia en los flujos de trabajo, utiliza el punto de conexión GET {baseURL}/v3/dcm/connections/lookup. El punto de conexión devuelve toda la información sobre la conexión de DCM, incluidas la fuente de datos y las credenciales relacionadas, así como la información para compartir.

Nota

El ConnectionID utilizado en este punto de conexión es diferente del ID utilizado en otros puntos de conexión de DCM. El ID se utiliza para hacer referencia a varios objetos DCM, mientras que ConnectionID solo se utiliza en flujos de trabajo para hacer referencia a la conexión de DCM de usuarios 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'

Compartir una conexión de DCM con usuarios y grupos específicos

Para compartir una conexión de DCM para la ejecución de Server con usuarios o grupos específicos, utiliza el punto de conexión PUT {baseURL}/v3/dcm/connections/{id}/sharing/execution.

Nota

Como este es un punto de conexión PUT, sobrescribe el uso compartido existente, en lugar de agregar usuarios o grupos de usuarios adicionales a la lista existente. La lista proporcionada de usuarios y grupos no puede estar vacía; para quitar el uso compartido existente, utiliza el punto de conexión DELETE.

Parámetros

  • id (cadena): obligatorio. Ingresa el ID de conexión de DCM que deseas compartir con otros usuarios o grupos.

  • sharingContract (cuerpo): obligatorio. Para actualizar el uso compartido de la ejecución, se requiere el parámetro sharingContract. Ambas matrices son necesarias, pero solo una se puede dejar vacía.

    • userIds (matriz de cadena): ingresa una lista de todos los ID de usuario con los que deseas compartir la conexión. Deja una matriz vacía si no hay usuarios con los que compartir (solo grupos de usuarios).

    • userGroupIds (matriz de cadena): ingresa una lista de todos los ID de grupo de usuarios con los que compartir la conexión. Deja una matriz vacía si no hay grupos de usuarios con los que compartir (solo usuarios).

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"
    ]
  }'

Dejar de compartir una conexión de DCM

Para dejar de compartir una conexión de DCM, utiliza el punto de conexión 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'

Crear o actualizar una conexión de DCM

Para crear o actualizar una conexión de DCM, utiliza el punto de conexión POST {baseURL}/v3/dcm/connections.

Un punto de conexión único sirve tanto para crear como actualizar funciones, diferenciadas en función de si los ID de objeto se incluyen en la solicitud. La reutilización de fuentes de datos o credenciales existentes no se admite actualmente cuando se crean nuevas conexiones.

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 connection

    • Connection.credentials.<credRole>.object.parameters: for each Credential role

    • Connection.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:

    1. Create a DCM Connection in the Alteryx Server UI for your target technology.

    2. Query the Connection via API: GET /v3/dcm/connections/{id}

    3. 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. See Connection.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. The object 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 and oauthTokens <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. See Connection.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": {}
            }
        }
    }
}'

Eliminar una conexión de DCM

Para eliminar una conexión de DCM, utiliza el punto de conexión DELETE {baseURL}/v3/dcm/connections/{id}. La fuente de datos y las credenciales también se eliminarán, a menos que se utilicen en cualquier otra conexión.

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'

Puntos de conexión de DCME para administradores

Puntos de conexión que pueden utilizar los administradores con acceso a 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 un registro de conexión de DCM

Para recuperar un registro de conexión de DCM, utiliza el punto de conexión 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 una lista de registros de conexión de DCM

Para recuperar una lista de todos los registros de conexión de DCM presentes en Server, utiliza el punto de conexión GET {baseURL}/v3/dcm/admin/connections.

Parámetros

Ambos parámetros son filtros que se pueden combinar. Si se utiliza connectionId y visibleBy en conjunto, se devolverá la conexión con ConnectionID especificado, visible por el usuario especificado.

  • connectionId (cadena): opcional. Filtra las conexiones en función de su connectionID, como se hace referencia desde un flujo de trabajo. Se pueden devolver múltiples conexiones para un único connectionID si la conexión se comparte para colaboración.

  • visibleBy (cadena): opcional. Ingresa el ID de usuario. Si está presente, filtra los resultados al mismo resultado que para todas las conexiones disponibles para el usuario especificado.

curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3&visibleBy=bc7cb7b47c33' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Crear o actualizar una conexión de DCM en nombre del usuario

Para crear o actualizar un registro de conexión de DCM en nombre de un usuario, utiliza el punto de conexión 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": {}
              }
            }
          }
        }
      }
    }
  }'

Dejar de compartir una conexión de DCM compartida para ejecución

Para dejar de compartir una conexión de DCM cuyo tipo de uso compartido se ha definido como Compartido para la ejecución, utiliza el punto de conexión DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/execution.

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'

Dejar de compartir una conexión de DCM compartida para colaboración

Para dejar de compartir una Conexión de DCM cuyo tipo de uso compartido se ha definido como Compartido para la colaboración, utiliza el punto de conexión 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'

Eliminar una conexión de DCM

Para eliminar un registro de Conexión de DCM, utiliza el punto de conexión DELETE {baseURL}/v3/dcm/admin/connections/{objectId}. La fuente de datos y las credenciales también se eliminarán, a menos que se utilicen en cualquier otra conexión.

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'

Recuperar todas las reglas de manejo de conexión de DCM

Para recuperar todas las reglas de manejo de conexión de DCM, utiliza el punto de conexión GET {baseURL}/v3/dcm/admin/connectionhandlingrules.

Ve a Manejo de conexiones de DCM para obtener más información.

Parámetros

Sin parámetros.

curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Recuperar una regla de manejo de conexión de DCM específica

Para recuperar una regla de manejo de conexión de DCM específica, utiliza el punto de conexión GET {baseURL}/v3/dcm/admin/connectionhandlingrules/{id}.

Parámetros

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'

Agregar o actualizar una regla de manejo de conexión de DCM

Para agregar una nueva regla de manejo de conexión de DCM o actualizar una existente, utiliza el punto de conexión POST {baseURL}/v3/dcm/admin/connectionhandlingrules.

Parámetros

Ingresa los siguientes parámetros para crear o actualizar una regla de manejo de conexión de DCM:

  • rule (cuerpo): obligatorio. La ConnectionHandlingRule de DCM que debe crearse o actualizarse.

    • id (cadena): opcional. El ID de la regla de manejo de conexión de DCM. Ingresa un ID de regla de manejo de conexión de DCM si deseas actualizar una regla de manejo de conexión existente. Omite este paso si deseas crear una nueva regla de manejo de conexión.

    • sourceConnectionId (cadena): ingresa un sourceConnectionId, con referencia a un ConnectionId que se reemplazará en la ejecución del flujo de trabajo. No es necesario que la conexión exista en el Server (los flujos de trabajo que hacen referencia a ella todavía se pueden ejecutar). No se puede utilizar en otra regla existente, ya sea una conexión fuente u objetivo.

    • sourceConnectionTitle (cadena): ingresa un nombre personalizado o una descripción de la conexión fuente.

    • targetConnectionId (cadena): ingresa un targetConnectionId. Debe hacer referencia a una conexión de DCM presente en el Server.

    • targetConnectionTitle (cadena): ingresa un nombre personalizado o una descripción de la conexión objetivo.

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"
}'

Eliminar una regla de manejo de conexión de DCM existente

Para eliminar una regla de manejo de conexión de DCM existente, utiliza el punto de conexión DELETE {baseURL}/v3/dcm/admin/connectionhandlingrules/{id}.

Parámetros

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'

Relaciones entre objetos

Si creas una conexión de DCM, puedes utilizar los objetos creados de la siguiente manera:

Objeto creado:

  • id” (por ejemplo, “id”: “c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3”)

  • connectionId” (por ejemplo, “id”: “c0332423423-86cc-4e7e-93a3-d500cca9a3f3”)

Puedes usarlo como:

Administrador: