Skip to main content

Endpoint DCME

Endpoint e parametri DCME

Gli endpoint DCME sono suddivisi in due gruppi: endpoint DCME per gli utenti e endpoint DCME per gli amministratori. Tutti gli endpoint DCME richiedono la configurazione di TLS su Server.

Per ulteriori informazioni sulle relazioni tra oggetti e su come utilizzarle nell'API, consulta la sezione Relazioni tra oggetti.

Per ulteriori informazioni sulle connessioni dati, consulta le pagine di assistenzaDCM - Server e Data Connection Manager (DCM): interfaccia utente di Server.DCM - ServerData Connection Manager (DCM): interfaccia utente di 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.

Endpoint DCME per gli utenti

Questi endpoint possono essere utilizzati dagli utenti con accesso all'API:

Nota

  • All API endpoints return individual user data (each user can only see and manage their own connections).

  • All examples are in PowerShell.

Recupero del record di una connessione DCM

Per recuperare il record di una connessione DCM, utilizza l'endpoint GET {baseURL}/v3/dcm/connections/{id}. L'endpoint restituisce tutte le informazioni relative alla connessione DCM, incluse l'origine dati e le credenziali, nonché le informazioni di condivisione.

Parametri

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'

Recupero di una connessione DCM a cui fanno riferimento i flussi di lavoro

Per recuperare il record di una connessione DCM a cui fanno riferimento i flussi di lavoro, utilizza l'endpoint GET {baseURL}/v3/dcm/connections/lookup. L'endpoint restituisce tutte le informazioni relative alla connessione DCM, incluse l'origine dati e le credenziali, nonché le informazioni di condivisione.

Nota

Il parametro ConnectionID utilizzato in questo endpoint è diverso dal parametro ID utilizzato in altri endpoint DCM. ID viene utilizzato per fare riferimento a vari oggetti DCM, mentre ConnectionID è utilizzato nei flussi di lavoro solo per fare riferimento alla connessione DCM per utenti specifici.

Parametri

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'

Condivisione di una connessione DCM con utenti e gruppi specificati

Per condividere una connessione DCM per l'esecuzione di Server con utenti o gruppi specificati, utilizza l'endpoint PUT {baseURL}/v3/dcm/connections/{id}/sharing/execution.

Nota

Poiché si tratta di un endpoint PUT, sovrascrive la condivisione esistente anziché aggiungere altri utenti o gruppi di utenti all'elenco esistente. L'elenco di utenti e gruppi fornito non può essere vuoto; per rimuovere la condivisione esistente, utilizza l'endpoint DELETE.

Parametri

  • id (stringa): obbligatorio. Immetti l'ID della connessione DCM che desideri condividere con altri utenti o gruppi.

  • sharingContract (corpo): obbligatorio. Il parametro sharingContract è obbligatorio per aggiornare la condivisione delle responsabilità di esecuzione. Sono necessari entrambi gli array, ma solo uno può essere lasciato vuoto.

    • userIds (array di stringhe): immetti un elenco degli ID di tutti gli utenti con cui condividere la connessione. Lascia un array vuoto se non sono presenti utenti per la condivisione (solo gruppi di utenti).

    • userGroupIds (array di stringhe): immetti un elenco di ID di tutti i gruppi di utenti con cui condividere la connessione. Lascia un array vuoto se non sono presenti gruppi di utenti per la condivisione (solo utenti).

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

Annullamento della condivisione di una connessione DCM

Per annullare la condivisione di una connessione DCM, utilizza l'endpoint DELETE {baseURL}/v3/dcm/connections/{id}/sharing/execution.

Parametri

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'

Creazione o aggiornamento di una connessione DCM

Per creare o aggiornare una connessione DCM, utilizza l'endpoint POST {baseURL}/v3/dcm/connections.

Un unico endpoint può essere utilizzato per le funzioni di creazione e di aggiornamento, a seconda della presenza o meno degli ID degli oggetti nella richiesta. Il riutilizzo di origini dati o credenziali esistenti non è attualmente supportato durante la creazione di nuove connessioni.

Parametri

  • 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": {}
            }
        }
    }
}'

Elimina una connessione DCM

Per eliminare una connessione DCM, utilizza l'endpoint DELETE {baseURL}/v3/dcm/connections/{id}. Verranno eliminate anche l'origine dati e le credenziali, a meno che non siano utilizzate in altre connessioni.

Parametri

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'

Endpoint DCME per gli amministratori

Endpoint che possono essere utilizzati dagli amministratori con accesso all'API:

Nota

  • All admin API endpoints return all data available on the Server across all users, regardless of ownership.

  • All examples are in PowerShell.

Recupero del record di una connessione DCM

Per recuperare un record di una connessione DCM, utilizza l'endpoint GET {baseURL}/v3/dcm/admin/connections/{objectId}.

Parametri

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'

Recupero di un elenco di record di connessioni DCM

Per recuperare un elenco di tutti i record delle connessione DCM presenti su Server, utilizza l'endpoint GET {baseURL}/v3/dcm/admin/connections.

Parametri

Entrambi i parametri sono filtri che possono essere combinati. L'uso congiunto di connectionId e visibleBy restituirà la connessione con il parametro ConnectionID specificato, visibile dall'utente specificato.

  • collectionId (stringa): opzionale. Filtra le connessioni in base al relativo connectionID a cui fa riferimento un flusso di lavoro. Se la connessione è condivisa per la collaborazione, un singolo parametro connectionID può restituire più connessioni.

  • visibleBy (stringa): opzionale. Immetti l'ID utente. Se è presente, filtra i risultati con lo stesso risultato di tutte le connessioni disponibili per l'utente specificato.

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

Creazione o aggiornamento di una connessione DCM per conto di un utente

Per creare o aggiornare il record di una connessione DCM per conto di un utente, utilizza l'endpoint 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": {}
              }
            }
          }
        }
      }
    }
  }'

Annullamento della condivisione di una connessione DCM condivisa per l'esecuzione

Per annullare la condivisione di una connessione DCM condivisa per l'esecuzione, utilizza l'endpoint DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/execution endpoint.

Parametri

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'

Annullamento della condivisione di una connessione DCM condivisa per la collaborazione

Per annullare la condivisione di una connessione DCM condivisa per la collaborazione, utilizza l'endpoint DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/collaboration.

Parametri

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'

Elimina una connessione DCM

Per eliminare il record di una connessione DCM, utilizza l'endpoint DELETE {baseURL}/v3/dcm/admin/connections/{objectId}. Verranno eliminate anche l'origine dati e le credenziali, a meno che non siano utilizzate in altre connessioni.

Parametri

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'

Recupera tutte le regole di gestione della connessione DCM

Per recuperare tutte le regole di gestione della connessione DCM, utilizza l'endpoint GET {baseURL}/v3/dcm/admin/connectionhandlingrules.

Per ulteriori informazioni, consulta Gestione della connessione DCM.

Parametri

Nessun parametro.

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

Recupera una regola specifica di gestione della connessione DCM

Per recuperare una sola regola di gestione della connessione DCM, utilizza l'endpoint GET {baseURL}/v3/dcm/admin/connectionhandlingrules/{id}.

Parametri

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'

Aggiunge o aggiorna una regola di gestione della connessione DCM

Per aggiungere una nuova regola di gestione della connessione DCM o aggiornarne una esistente, utilizza l'endpoint POST {baseURL}/v3/dcm/admin/connectionhandlingrules.

Parametri

Immetti i seguenti parametri per creare o aggiornare una regola di gestione della connessione DCM:

  • rule (corpo): obbligatorio. DCM ConnectionHandlingRule da creare o aggiornare.

    • id (stringa): opzionale. ID della regola di gestione della connessione DCM Immetti un ID della regola di gestione della connessione DCM se desideri aggiornare una regola di gestione della connessione esistente. Salta se desideri creare una nuova regola di gestione della connessione.

    • sourceConnectionId (stringa): immetti un valore sourceConnectionId, facendo riferimento a un ConnectionId da sostituire nel momento dell'esecuzione del flusso di lavoro. La connessione non deve necessariamente esistere su Server (i flussi di lavoro che fanno riferimento ad essa possono comunque essere eseguiti). Non può essere utilizzato in un'altra regola esistente, che si tratti di una connessione di origine o di destinazione.

    • sourceConnectionTitle (stringa): immetti un nome personalizzato o una descrizione della connessione di origine.

    • targetConnectionId (stringa): immetti un valore targetConnectionId. Deve fare riferimento a una connessione DCM presente su Server.

    • targetConnectionTitle (stringa): immetti un nome personalizzato o una descrizione della connessione di destinazione.

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

Eliminazione di una regola di gestione della connessione DCM esistente

Per eliminare una regola di gestione della connessione DCM esistente, utilizza l'endpoint DELETE {baseURL}/v3/dcm/admin/connectionhandlingrules/{id}.

Parametri

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'

Relazioni tra oggetti

Se stai creando una connessione DCM, puoi utilizzare gli oggetti creati nel modo seguente:

Oggetto creato:

  • "id" (ad esempio, "id": "c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3")

  • "connectionId" (ad esempio, "id": "c0332423423-86cc-4e7e-93a3-d500cca9a3f3")

Puoi utilizzarlo come:

Admin: