DCME-Endpunkte und Parameter
Die DCME-Endpunkte sind in zwei Gruppen unterteilt: DCME-Endpunkte für Benutzer und DCME-Endpunkte für Administratoren. Für alle DCME-Endpunkte muss auf dem Server TLS konfiguriert sein.
Weitere Informationen zu Objektbeziehungen und deren Verwendung in der API finden Sie im Abschnitt Objektbeziehungen.
Weitere Informationen über Datenverbindungen finden Sie auf den Hilfeseiten DCM – Server und Data Connection Manager: Server-Benutzeroberfläche.
“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
.
Diese Endpunkte können von Benutzern mit API-Zugriff verwendet werden:
Anmerkung
All API endpoints return individual user data (each user can only see and manage their own connections).
All examples are in PowerShell.
Um einen DCM-Verbindungsdatensatz abzurufen, verwenden Sie den Endpunkt GET {baseURL}/v3/dcm/connections/{id}. Der Endpunkt gibt alle Informationen über die DCM-Verbindung zurück, einschließlich der zugehörigen Datenquelle und Anmeldedaten sowie der Informationen zur Freigabe.
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'
Um einen DCM-Verbindungsdatensatz so abzurufen, wie er in Workflows referenziert wird, verwenden Sie den Endpunkt GET {baseURL}/v3/dcm/connections/lookup. Der Endpunkt gibt alle Informationen über die DCM-Verbindung zurück, einschließlich der zugehörigen Datenquelle und Anmeldedaten sowie der Informationen zur Freigabe.
Anmerkung
Die in diesem Endpunkt verwendete connectionId unterscheidet sich von der in anderen DCM-Endpunkten verwendeten ID. Der Parameter „id“ wird verwendet, um verschiedene DCM-Objekte zu referenzieren, während connectionId nur in Workflows verwendet wird, um die DCM-Verbindung für bestimmte Benutzer zu referenzieren.
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'
Um eine DCM-Verbindung für die Serverausführung mit angegebenen Benutzern oder Gruppen freizugeben, verwenden Sie den Endpunkt PUT {baseURL}/v3/dcm/connections/{id}/sharing/execution.
Anmerkung
Da es sich um einen PUT-Endpunkt handelt, überschreibt er die vorhandene Freigabe, statt zusätzliche Benutzer oder Benutzergruppen zur vorhandenen Liste hinzuzufügen. Die angegebene Liste der Benutzer und Gruppen darf nicht leer sein. Um die vorhandene Freigabe zu entfernen, verwenden Sie den DELETE-Endpunkt.
id (Zeichenfolge): erforderlich. Geben Sie die DCM-Verbindungs-ID ein, die Sie für andere Benutzer oder Gruppen freigeben möchten.
sharingContract (Text): erforderlich. Zum Aktualisieren der Ausführungsfreigabe ist der Parameter „sharingContract“ erforderlich. Beide Arrays sind erforderlich, wobei nur eines leer bleiben kann.
userIds (Zeichenfolgen-Array): Geben Sie eine Liste aller Benutzer-IDs ein, für die die Verbindung freigegeben werden soll. Lassen Sie das Array leer, wenn die Verbindung für keine Benutzer (sondern nur für Benutzergruppen) freigegeben werden soll.
userGroupIds (Zeichenfolgen-Array): Geben Sie eine Liste aller Benutzergruppen-IDs ein, für die die Verbindung freigegeben werden soll. Lassen Sie das Array leer, wenn die Verbindung für keine Benutzergruppen (sondern nur für einzelne Benutzer) freigegeben werden soll.
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"
]
}'
Um die Freigabe einer DCM-Verbindung aufzuheben, verwenden Sie den Endpunkt 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'
Um eine DCM-Verbindung zu erstellen oder zu aktualisieren, verwenden Sie den Endpunkt POST {baseURL}/v3/dcm/connections.
Ein einzelner Endpunkt dient sowohl für Erstellungs- als auch für Aktualisierungsfunktionen, wobei danach unterschieden wird, ob in der Anforderung Objekt-IDs enthalten sind. Die Wiederverwendung vorhandener Datenquellen oder Anmeldedaten wird derzeit beim Erstellen neuer Verbindungen nicht unterstützt.
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.
Anmerkung
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.
Anmerkung
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": {}
}
}
}
}'
Um eine DCM-Verbindung zu löschen, verwenden Sie den Endpunkt DELETE {baseURL}/v3/dcm/connections/{id}. Die Datenquelle und die Anmeldedaten werden ebenfalls gelöscht, es sei denn, sie werden in einer anderen Verbindung verwendet.
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'
Endpunkte, die von Administratoren mit API-Zugriff verwendet werden können:
DCM-Verbindung im Namen eines Benutzers erstellen oder aktualisieren
Freigabe einer DCM-Verbindung aufheben, die zur Ausführung freigegeben wurde
Freigabe einer DCM-Verbindung aufheben, die für die Zusammenarbeit freigegeben wurde
Eine bestimmte Regel für die DCM-Verbindungsbehandlung abrufen
Eine Regel zur DCM-Verbindungsbehandlung hinzufügen oder aktualisieren
Anmerkung
All admin API endpoints return all data available on the Server across all users, regardless of ownership.
All examples are in PowerShell.
Um einen DCM-Verbindungsdatensatz abzurufen, verwenden Sie den Endpunkt 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'
Um eine Liste aller auf dem Server vorhandenen DCM-Verbindungsdatensätze abzurufen, verwenden Sie den Endpunkt GET {baseURL}/v3/dcm/admin/connections.
Beide Parameter sind Filter, die kombiniert werden können. Wenn connectionId und visibleBy zusammen verwendet werden, wird die Verbindung mit der angegebenen connectionId zurückgegeben, die für den angegebenen Benutzer sichtbar ist.
connectionId (Zeichenfolge): optional. Filtert Verbindungen nach der connectionId wie in einem Workflow referenziert. Für eine einzelne connectionId können mehrere Verbindungen zurückgegeben werden, wenn die Verbindung für die Zusammenarbeit freigegeben wurde.
visibleBy (Zeichenfolge): optional. Geben Sie eine Benutzer-ID ein. Wenn vorhanden, werden dadurch die Ergebnisse nach demselben Ergebnis gefiltert wie für alle Verbindungen, die dem angegebenen Benutzer zur Verfügung stehen.
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3&visibleBy=bc7cb7b47c33' `
--header 'Authorization: Bearer BearerTokenGoesHere'
Um einen DCM-Verbindungsdatensatz im Namen eines Benutzers zu erstellen oder zu aktualisieren, verwenden Sie den Endpunkt POST {baseURL}/v3/dcm/admin/connections.
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": {}
}
}
}
}
}
}
}'
Um die Freigabe einer DCM-Verbindung aufzuheben, deren Freigabetyp als „Zur Ausführung freigegeben“ definiert ist, verwenden Sie den Endpunkt 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'
Um die Freigabe einer DCM-Verbindung aufzuheben, deren Freigabetyp als „Für Zusammenarbeit freigegeben“ definiert ist, verwenden Sie den Endpunkt 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'
Um einen DCM-Verbindungsdatensatz zu löschen, verwenden Sie den Endpunkt DELETE {baseURL}/v3/dcm/admin/connections/{objectId}. Die Datenquelle und die Anmeldedaten werden ebenfalls gelöscht, es sei denn, sie werden in einer anderen Verbindung verwendet.
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'
Um alle Regeln für die DCM-Verbindungsbehandlung abzurufen, verwenden Sie den Endpunkt GET {baseURL}/v3/dcm/admin/connections/.
Weitere Informationen finden Sie unter DCM-Verbindungsbehandlung.
Keine Parameter.
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules' `
--header 'Authorization: Bearer BearerTokenGoesHere'
Um eine bestimmte DCM-Verbindungsbehandlungsregel abzurufen, verwenden Sie den Endpunkt GET {baseURL}/v3/dcm/admin/connections/{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'
Um eine neue DCM-Verbindungsbehandlungsregel hinzuzufügen oder eine vorhandene Regel zu aktualisieren, verwenden Sie den Endpunkt POST /v3/dcm/admin/connectionhandlingrules{baseURL}.
Mit den folgenden Parameter können Sie eine DCM-Verbindungsbehandlungsregel erstellen oder aktualisieren:
rule (Text): Erforderlich. Die DCM-Verbindungsbehandlungsregel, die erstellt oder aktualisiert werden soll.
id (Zeichenfolge): optional. Die ID für die DCM-Verbindungsbehandlungsregel. Geben Sie eine DCM-Verbindungsbehandlungsregel-ID ein, wenn Sie eine vorhandene Verbindungsbehandlungsregel aktualisieren möchten. Überspringen Sie dies, wenn Sie eine neue Verbindungsbehandlungsregel erstellen möchten.
sourceConnectionId (Zeichenfolge): Geben Sie eine sourceConnectionId ein, die auf eine ConnectionId verweist, die bei der Workflow-Ausführung ersetzt werden soll. Die Verbindung muss nicht auf dem Server vorhanden sein. Workflows, die darauf verweisen, können trotzdem ausgeführt werden. Sie kann für keine andere Regel verwendet werden, ob als Quell- oder Zielverbindung.
sourceConnectionTitle (Zeichenfolge): Geben Sie einen benutzerdefinierten Namen oder eine Beschreibung der Quellverbindung ein.
targetConnectionId (Zeichenfolge): Geben Sie eine targetConnectionId ein. Diese muss auf eine auf dem Server vorhandene DCM-Verbindung verweisen.
targetConnectionTitle (Zeichenfolge): Geben Sie einen benutzerdefinierten Namen oder eine Beschreibung der Zielverbindung ein.
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"
}'
Um eine vorhandene DCM-Verbindungsbehandlungsregel zu löschen, verwenden Sie den Endpunkt 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'
Wenn Sie eine DCM-Verbindung erstellen, können Sie erstellte Objekte wie folgt verwenden:
Erstelltes Objekt:
„id“ (z. B. "id": "c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3")
„connectionId“ (z. B. "id": "c0332423423-86cc-4e7e-93a3-d500cca9a3f3")
Sie können sie wie folgt verwenden:
id, wenn Sie einen DCM-Verbindungsdatensatz abrufen möchten
connectionId, wenn Sie eine DCM-Verbindung wie in Workflows referenziert abrufen möchten
id, wenn Sie eine DCM-Verbindung für angegebene Benutzer und Gruppen freigeben möchten
id, wenn Sie eine DCM-Verbindung aktualisieren möchten
id, wenn Sie eine DCM-Verbindung löschen möchten
id, wenn Sie die Freigabe einer DCM-Verbindung aufheben möchten
Admin:
id, wenn Sie einen DCM-Verbindungsdatensatz abrufen möchten
ownerId (userId), wenn Sie eine DCM-Verbindung im Namen eines Benutzers erstellen möchten
id, wenn Sie eine DCM-Verbindung im Namen eines Benutzers aktualisieren möchten
id, wenn Sie die Freigabe einer DCM-Verbindung, die zur Ausführung freigegeben wurde, aufheben möchten
id, wenn Sie die Freigabe einer DCM-Verbindung, die für die Zusammenarbeit freigegeben wurde, aufheben möchten
id, wenn Sie eine DCM-Verbindung löschen möchten#dcm-verbindung-löschen-7047212-1