DocumentaçãoExperience PlatformGuia dos conectores de origem

Conectar o Microsoft Dynamics ao Experience Platform usando a API Flow Service

Última atualização: 4 de abril de 2025
  • Tópicos:

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:

Autenticação básica
CredencialDescrição
serviceUriA URL de serviço da instância Dynamics.
usernameO nome de usuário da sua conta de usuário Dynamics.
passwordA senha da sua conta Dynamics.
Autenticação da entidade de serviço e da chave
CredencialDescrição
servicePrincipalIdA 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.
servicePrincipalKeyA 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

TIP
Depois de criada, você não pode alterar o tipo de autenticação de uma conexão de base Dynamics. Para alterar o tipo de autenticação, você deve criar uma nova conexão base.

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
Autenticação básica

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.

Selecione para exibir o exemplo de solicitaçã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 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"
      }
  }'
Propriedade
Descrição
auth.params.serviceUri
O URI de serviço associado à sua instância Dynamics.
auth.params.username
O nome de usuário associado à sua conta Dynamics.
auth.params.password
A senha associada à sua conta Dynamics.
connectionSpec.id
A ID da especificação de conexão Dynamics: 38ad80fe-8b06-4938-94f4-d4ee80266b07

Resposta

Uma resposta bem-sucedida retorna a conexão base recém-criada, incluindo seu identificador exclusivo (id).

Selecione para exibir o exemplo de resposta
{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}
Autenticação baseada na chave da entidade de serviço

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.

Selecione para exibir o exemplo de solicitaçã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"
      }
  }'
Propriedade
Descrição
auth.params.serviceUri
O URI de serviço associado à sua instância Dynamics.
auth.params.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.
auth.params.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.
connectionSpec.id
A ID da especificação de conexão Dynamics: 38ad80fe-8b06-4938-94f4-d4ee80266b07

Resposta

Uma resposta bem-sucedida retorna a conexão recém-criada, incluindo seu identificador exclusivo (id).

Selecione para exibir o exemplo de resposta
{
    "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
Parâmetros de consulta
Descrição
{BASE_CONNECTION_ID}
A ID da conexão base. Use essa ID para explorar o conteúdo e a estrutura da fonte.

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.

Selecione para exibir o exemplo de solicitação
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.

Selecione para exibir o exemplo de resposta
[
    {
        "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

NOTE
Você só pode usar atributos que não sejam de pesquisa ao usar a abordagem de chave primária para otimização.

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}
Parâmetros de consulta
Descrição
{BASE_CONNECTION_ID}
A ID da conexão base. Use essa ID para explorar o conteúdo e a estrutura da fonte.
preview
Um valor booleano que permite a visualização de dados.
{OBJECT}
O objeto Dynamics que você deseja explorar.
{OBJECT_TYPE}
O tipo do objeto.
previewCount
Uma restrição que limita a visualização retornada a apenas um determinado número de registros.
{PRIMARY_KEY}
A chave primária da tabela que você está recuperando para visualização.

Solicitação

Selecione para exibir o exemplo de 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
Parâmetro de consulta
Descrição
{BASE_CONNECTION_ID}
A ID da conexão base. Use essa ID para explorar o conteúdo e a estrutura da fonte.
{TABLE_PATH}
O caminho para a tabela específica que você deseja explorar.

Solicitação

A solicitação a seguir recupera a estrutura e o conteúdo de uma tabela Dynamics com o caminho workflowdependency.

Selecione para exibir o exemplo de solicitação
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.

Selecione para exibir o exemplo de resposta
{
    "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
Parâmetro de consulta
Descrição
{BASE_CONNECTION_ID}
A ID da conexão base. Use essa ID para explorar o conteúdo e a estrutura da fonte.
{VIEW_PATH}
O caminho para a exibição que você deseja inspecionar.

Solicitação

A solicitação a seguir recupera accountView1.

Selecione para exibir o exemplo de solicitação
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.

Selecione para exibir o exemplo de resposta
{
    "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
Parâmetro de consulta
Descrição
{BASE_CONNECTION_ID}
A ID da conexão base. Use essa ID para explorar o conteúdo e a estrutura da fonte.
{VIEW_PATH}
O caminho para a exibição que você deseja inspecionar.

Solicitação

A solicitação a seguir visualiza o conteúdo de accountView1.

Selecione para exibir o exemplo de solicitação
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.

Selecione para exibir o exemplo de resposta
{
    "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.

Selecione para exibir o exemplo de solicitação
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.

Selecione para exibir o exemplo de resposta
{
    "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.

Selecione para exibir o exemplo de solicitação
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"
      }
  }'
Propriedade
Descrição
baseConnectionId
A ID da conexão base.
data.format
O formato dos dados.
params.tableName
O nome da tabela em Dynamics.
params.primaryKey
A chave primária da tabela que otimizará as consultas.
connectionSpec.id
A ID de especificação da conexão que corresponde à origem Dynamics.

Resposta

Uma resposta bem-sucedida retorna a ID de conexão de origem recém-gerada e a tag correspondente.

Selecione para exibir o exemplo de resposta
{
    "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:

  • Explore a estrutura e o conteúdo das tabelas de dados usando a API Flow Service
  • Crie um fluxo de dados para trazer dados do CRM para o Experience Platform usando a API Flow Service
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089