Conectar o Microsoft Dynamics ao Experience Platform usando a API Flow Service
Criado para:
- Desenvolvedor
Leia este guia para saber como você pode conectar sua origem do Microsoft Dynamics à Adobe Experience Platform usando a Flow Service API.
Introdução
Este manual necessita de uma compreensão funcional dos seguintes componentes da Adobe Experience Platform:
- Fontes: o Experience Platform permite a assimilação de dados de várias fontes, ao mesmo tempo em que fornece a capacidade de estruturar, rotular e aprimorar os dados recebidos usando os serviços do Experience Platform.
- Sandboxes: a Experience Platform fornece sandboxes virtuais que particionam uma única instância do Experience Platform em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.
Uso de APIs do Experience Platform
Para obter informações sobre como fazer chamadas para APIs do Experience Platform com êxito, consulte o manual sobre introdução às APIs do Experience Platform.
As seções a seguir fornecem informações adicionais que você precisará saber para conectar com êxito o Experience Platform a uma conta do Dynamics usando a API Flow Service.
Coletar credenciais necessárias
Para que Flow Service se conecte a Dynamics, você deve fornecer valores para as seguintes propriedades de conexão:
Credencial | Descrição |
---|---|
serviceUri | A URL de serviço da instância Dynamics. |
username | O nome de usuário da sua conta de usuário Dynamics. |
password | A senha da sua conta Dynamics. |
Credencial | Descrição |
---|---|
servicePrincipalId | A ID de cliente da sua conta Dynamics. Essa ID é necessária ao usar a entidade de serviço e a autenticação baseada em chave. |
servicePrincipalKey | A chave secreta da entidade de serviço. Essa credencial é necessária ao usar a entidade de serviço e a autenticação baseada em chave. |
Para obter mais informações sobre a introdução, consulte este Dynamics documento.
Criar uma conexão básica
Uma conexão base retém informações entre sua origem e a Experience Platform, incluindo as credenciais de autenticação da origem, o estado atual da conexão e a ID de conexão base exclusiva. A ID de conexão básica permite explorar e navegar pelos arquivos de dentro da origem e identificar os itens específicos que deseja assimilar, incluindo informações sobre os tipos de dados e formatos.
Para criar uma ID de conexão base, faça uma solicitação POST para o ponto de extremidade /connections
ao fornecer suas credenciais de autenticação Dynamics como parte dos parâmetros de solicitação.
Formato da API
POST /connections
Para criar uma conexão base do Dynamics usando autenticação básica, faça uma solicitação POST para a API Flow Service enquanto fornece valores para os serviceUri
, username
e password
da sua conexão.
Solicitação
A solicitação a seguir cria uma conexão base para uma origem Dynamics usando autenticação básica.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Dynamics connection",
"description": "Dynamics connection using basic auth",
"auth": {
"specName": "Basic Authentication for Dynamics-Online",
"params": {
"serviceUri": "{SERVICE_URI}",
"username": "{USERNAME}",
"password": "{PASSWORD}"
}
},
"connectionSpec": {
"id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
"version": "1.0"
}
}'
auth.params.serviceUri
auth.params.username
auth.params.password
connectionSpec.id
38ad80fe-8b06-4938-94f4-d4ee80266b07
Resposta
Uma resposta bem-sucedida retorna a conexão base recém-criada, incluindo seu identificador exclusivo (id
).
{
"id": "4cb0c374-d3bb-4557-b139-5712880adc55",
"etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}
Para criar uma conexão base Dynamics usando a autenticação baseada em chave da entidade de serviço, faça uma solicitação POST para a API Flow Service enquanto fornece valores para os serviceUri
, servicePrincipalId
e servicePrincipalKey
da sua conexão.
Solicitação
A solicitação a seguir cria uma conexão base para uma origem Dynamics usando a autenticação básica baseada em chave de entidade de serviço.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Dynamics connection",
"description": "Dynamics connection using key-based authentication",
"auth": {
"specName": "Service Principal Key Based Authentication",
"params": {
"serviceUri": "{SERVICE_URI}",
"servicePrincipalId": "{SERVICE_PRINCIPAL_ID}",
"servicePrincipalKey": "{SERVICE_PRINCIPAL_KEY}"
}
},
"connectionSpec": {
"id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
"version": "1.0"
}
}'
auth.params.serviceUri
auth.params.servicePrincipalId
auth.params.servicePrincipalKey
connectionSpec.id
38ad80fe-8b06-4938-94f4-d4ee80266b07
Resposta
Uma resposta bem-sucedida retorna a conexão recém-criada, incluindo seu identificador exclusivo (id
).
{
"id": "4cb0c374-d3bb-4557-b139-5712880adc55",
"etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}
Explore suas tabelas de dados
Para explorar suas tabelas de dados do Dynamics, faça uma solicitação GET para o ponto de extremidade /connections/{BASE_CONNECTION_ID}/explore
e forneça sua ID de conexão básica como parte dos parâmetros de consulta.
Formato da API
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=root
{BASE_CONNECTION_ID}
Solicitação
A solicitação a seguir recupera a lista de tabelas e exibições disponíveis para uma origem Dynamics com a ID de conexão base: dd668808-25da-493f-8782-f3433b976d1e
.
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?objectType=root' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Resposta
Uma resposta bem-sucedida retorna o diretório de tabelas e exibições Dynamics no nível raiz.
[
{
"type": "table",
"name": "systemuserlicenses",
"path": "systemuserlicenses",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "table",
"name": "Process Dependency",
"path": "workflowdependency",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "view",
"name": "accountView1",
"path": "accountView1",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "view",
"name": "Inactive_ACC_custom",
"path": "Inactive_ACC_custom",
"canPreview": true,
"canFetchSchema": true
}
]
Usar a chave primária para otimizar a exploração de dados
Você pode otimizar suas consultas de exploração fornecendo primaryKey
como parte de seus parâmetros de consulta. Você deve especificar a chave primária da tabela Dynamics ao incluir primaryKey
como um parâmetro de consulta.
Formato da API
GET /connections/{BASE_CONNECTION_ID}/explore?preview=true&object={OBJECT}&objectType={OBJECT_TYPE}&previewCount=10&primaryKey={PRIMARY_KEY}
{BASE_CONNECTION_ID}
preview
{OBJECT}
{OBJECT_TYPE}
previewCount
{PRIMARY_KEY}
Solicitação
curl -X GET \
'https://platform-stage.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?preview=true&object=lead&objectType=table&previewCount=10&primaryKey=leadid' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Inspecionar a estrutura de uma tabela
Para inspecionar a estrutura de uma tabela específica, faça uma solicitação GET para /connections/{BASE_CONNECTION_ID}/explore
e forneça o caminho para a tabela específica como um parâmetro de consulta.
Formato da API
GET /connections/{BASE_CONNECTION_ID}/explore?object={TABLE_PATH}&objectType=table
{BASE_CONNECTION_ID}
{TABLE_PATH}
Solicitação
A solicitação a seguir recupera a estrutura e o conteúdo de uma tabela Dynamics com o caminho workflowdependency
.
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?object=workflowdependency&objectType=table' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Resposta
Uma resposta bem-sucedida retorna o conteúdo do caminho workflowdependency
.
{
"format": "flat",
"schema": {
"columns": [
{
"name": "first_name",
"type": "string",
"meta": {
"originalType": "String"
}
},
{
"name": "last_name",
"type": "string",
"meta": {
"originalType": "String"
}
},
{
"name": "email",
"type": "string",
"meta": {
"originalType": "String"
}
}
]
}
}
Inspecionar a estrutura de uma exibição
Em Dynamics, uma exibição se refere às colunas a serem exibidas, à largura de cada coluna, ao sistema padrão no qual uma lista de registros é classificada e aos filtros padrão aplicados para restringir quais registros aparecerão na lista.
Para inspecionar a estrutura de um modo de exibição, faça uma solicitação GET para /connections/{BASE_CONNECTION_ID}/explore
e especifique o caminho de modo de exibição nos parâmetros de consulta. Além disso, você deve especificar objectType
como view
.
Formato da API
GET /connections/{BASE_CONNECTION_ID}/explore?object={VIEW_PATH}&objectType=view
{BASE_CONNECTION_ID}
{VIEW_PATH}
Solicitação
A solicitação a seguir recupera accountView1
.
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?object=accountView1&objectType=view' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Resposta
Uma resposta bem-sucedida retorna a estrutura de accountView1
.
{
"format": "flat",
"schema": {
"columns": [
{
"name": "name",
"type": "string",
"meta": {
"originalType": "string"
},
"xdm": {
"type": "string"
}
},
{
"name": "fetchxml",
"type": "string",
"meta": {
"originalType": "string"
},
"xdm": {
"type": "string"
}
},
{
"name": "querytype",
"type": "integer",
"meta": {
"originalType": "int"
},
"xdm": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647
}
},
{
"name": "userqueryid",
"type": "string",
"meta": {
"originalType": "guid"
},
"xdm": {
"type": "string"
}
}
]
}
}
Visualizar exibição de tipo de entidade
Para visualizar o conteúdo de um modo de exibição, faça uma solicitação do GET para /connections/{BASE_CONNECTION_ID}/explore
e inclua o caminho de exibição e preview=true
nos parâmetros de consulta.
Formato da API
GET /connections/{BASE_CONNECTION_ID}/explore?object={VIEW_PATH}&preview=true&objectType=view
{BASE_CONNECTION_ID}
{VIEW_PATH}
Solicitação
A solicitação a seguir visualiza o conteúdo de accountView1
.
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/dd668808-25da-493f-8782-f3433b976d1e/explore?object=accountView1&preview=true&objectType=view' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Resposta
Uma resposta bem-sucedida retorna o conteúdo de accountView1
.
{
"format": "flat",
"schema": {
"columns": [
{
"name": "emailaddress1",
"type": "string",
"meta": {
"originalType": "string"
},
"xdm": {
"type": "string"
}
},
{
"name": "contactid",
"type": "string",
"meta": {
"originalType": "guid"
},
"xdm": {
"type": "string"
}
},
{
"name": "fullname",
"type": "string",
"meta": {
"originalType": "string"
},
"xdm": {
"type": "string"
}
}
]
},
"data": [
{
"contactid": "396e19de-0852-ec11-8c62-00224808a1df",
"fullname": "Tim Barr",
"emailaddress1": "barrtim@googlemedia.com"
}
]
}
Criar uma conexão de origem para assimilar a exibição
Para criar uma conexão de origem e assimilar uma exibição, faça uma solicitação POST para o ponto de extremidade /sourceConnections
, forneça o nome da tabela e especifique entityType
como view
no corpo da solicitação.
Formato da API
POST /sourceConnections
Solicitação
A solicitação a seguir cria uma conexão de origem Dynamics e assimila exibições.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Dynamics Source Connection",
"description": "Dynamics Source Connection",
"baseConnectionId": "dd668808-25da-493f-8782-f3433b976d1e",
"data": {
"format": "tabular",
"schema": null,
"properties": null
},
"params": {
"tableName": "Contacts with name TIM",
"entityType": "view"
},
"connectionSpec": {
"id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
"version": "1.0"
}
}'
Resposta
Uma resposta bem-sucedida retorna a ID de conexão de origem recém-gerada e a tag correspondente.
{
"id": "e566bab3-1b58-428c-b751-86b8cc79a3b4",
"etag": "\"82009592-0000-0200-0000-678121030000\""
}
Usar a chave primária para otimizar seu fluxo de dados
Você também pode otimizar o fluxo de dados do Dynamics especificando a chave primária como parte dos parâmetros do corpo da solicitação.
Formato da API
POST /sourceConnections
Solicitação
A solicitação a seguir cria uma conexão de origem Dynamics ao especificar a chave primária como contactid
.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Dynamics Source Connection",
"description": "Dynamics Source Connection",
"baseConnectionId": "dd668808-25da-493f-8782-f3433b976d1e",
"data": {
"format": "tabular"
},
"params": {
"tableName": "contact",
"primaryKey": "contactid"
},
"connectionSpec": {
"id": "38ad80fe-8b06-4938-94f4-d4ee80266b07",
"version": "1.0"
}
}'
baseConnectionId
data.format
params.tableName
params.primaryKey
connectionSpec.id
Resposta
Uma resposta bem-sucedida retorna a ID de conexão de origem recém-gerada e a tag correspondente.
{
"id": "e566bab3-1b58-428c-b751-86b8cc79a3b4",
"etag": "\"82009592-0000-0200-0000-678121030000\""
}
Próximas etapas
Seguindo este tutorial, você criou uma conexão de base Microsoft Dynamics usando a API Flow Service. Você pode usar essa ID de conexão básica nos seguintes tutoriais: