Documentazione Experience Platform Guida ai connettori di origini

Connetti Microsoft Dynamics ad Experience Platform utilizzando l'API Flow Service

Ultimo aggiornamento: 4 aprile 2025

Argomenti:

Creato per:

Sviluppatore

Leggi questa guida per scoprire come collegare l'origine Microsoft Dynamics a Adobe Experience Platform utilizzando Flow Service API.

Introduzione

Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:

Origini: Experience Platform consente di acquisire dati da varie origini e allo stesso tempo di strutturare, etichettare e migliorare i dati in arrivo tramite i servizi Experience Platform.
Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza Experience Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.

Utilizzo delle API di Experience Platform

Per informazioni su come effettuare correttamente chiamate alle API di Experience Platform, consulta la guida introduttiva alle API di Experience Platform.

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per connettere correttamente Experience Platform a un account Dynamics utilizzando l'API Flow Service.

Raccogli le credenziali richieste

Affinché Flow Service possa connettersi a Dynamics, è necessario fornire i valori per le proprietà di connessione seguenti:

Autenticazione di base

Credenziali	Descrizione
`serviceUri`	L'URL del servizio dell'istanza Dynamics.
`username`	Il nome utente per l'account utente Dynamics.
`password`	Password per l'account Dynamics.

Autenticazione Service-principal e chiave

Credenziali	Descrizione
`servicePrincipalId`	ID client dell'account Dynamics. Questo ID è necessario quando si utilizza l’entità servizio e l’autenticazione basata su chiave.
`servicePrincipalKey`	Chiave segreta dell'entità servizio. Questa credenziale è necessaria quando si utilizza l'entità servizio e l'autenticazione basata su chiave.

Per ulteriori informazioni, consulta questo Dynamics documento.

Creare una connessione di base

TIP

Una volta creata, non è possibile modificare il tipo di autenticazione di una connessione di base Dynamics. Per modificare il tipo di autenticazione, è necessario creare una nuova connessione di base.

Una connessione di base mantiene le informazioni tra l’origine e Experience Platform, incluse le credenziali di autenticazione dell’origine, lo stato corrente della connessione e l’ID univoco della connessione di base. L’ID della connessione di base consente di esplorare e navigare tra i file dall’interno dell’origine e identificare gli elementi specifici che desideri acquisire, comprese le informazioni relative ai tipi di dati e ai formati.

Per creare un ID connessione di base, eseguire una richiesta POST all'endpoint /connections fornendo le credenziali di autenticazione Dynamics come parte dei parametri della richiesta.

Formato API

POST /connections

Autenticazione di base

Per creare una connessione di base Dynamics utilizzando l'autenticazione di base, eseguire una richiesta POST all'API Flow Service fornendo i valori per serviceUri, username e password della connessione.

Richiesta

La richiesta seguente crea una connessione di base per un'origine Dynamics utilizzando l'autenticazione di base.

Seleziona per visualizzare l’esempio di richiesta

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

Proprietà

Descrizione

auth.params.serviceUri

L'URI del servizio associato all'istanza Dynamics.

auth.params.username

Il nome utente associato al tuo account Dynamics.

auth.params.password

La password associata al tuo account Dynamics.

connectionSpec.id

ID della specifica di connessione Dynamics: 38ad80fe-8b06-4938-94f4-d4ee80266b07

Risposta

In caso di esito positivo, la risposta restituisce la connessione di base appena creata, incluso il relativo identificatore univoco (id).

Seleziona per visualizzare l’esempio di risposta

{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}

Autenticazione basata su chiave entità servizio

Per creare una connessione di base Dynamics utilizzando l'autenticazione basata sulla chiave dell'entità servizio, eseguire una richiesta POST all'API Flow Service fornendo i valori per serviceUri, servicePrincipalId e servicePrincipalKey della connessione.

Richiesta

La richiesta seguente crea una connessione di base per un'origine Dynamics utilizzando l'autenticazione basata su chiave dell'entità servizio di base.

Seleziona per visualizzare l’esempio di richiesta

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

Proprietà

Descrizione

auth.params.serviceUri

L'URI del servizio associato all'istanza Dynamics.

auth.params.servicePrincipalId

ID client dell'account Dynamics. Questo ID è necessario quando si utilizza l’entità servizio e l’autenticazione basata su chiave.

auth.params.servicePrincipalKey

Chiave segreta dell'entità servizio. Questa credenziale è necessaria quando si utilizza l'entità servizio e l'autenticazione basata su chiave.

connectionSpec.id

ID della specifica di connessione Dynamics: 38ad80fe-8b06-4938-94f4-d4ee80266b07

Risposta

In caso di esito positivo, la risposta restituisce la connessione appena creata, incluso il relativo identificatore univoco (id).

Seleziona per visualizzare l’esempio di risposta

{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"9e0052a2-0000-0200-0000-5e35tb330000\""
}

Esplora le tabelle di dati

Per esplorare le tabelle dati Dynamics, effettua una richiesta GET all'endpoint /connections/{BASE_CONNECTION_ID}/explore e fornisci l'ID connessione di base come parte dei parametri della query.

Formato API

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=root

Parametri della query

Descrizione

{BASE_CONNECTION_ID}

ID della connessione di base. Usa questo ID per esplorare il contenuto e la struttura dell’origine.

Richiesta

La richiesta seguente recupera l'elenco di tabelle e viste disponibili per un'origine Dynamics con ID connessione di base: dd668808-25da-493f-8782-f3433b976d1e.

Seleziona per visualizzare l’esempio di richiesta

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' \

Risposta

In caso di esito positivo, la risposta restituisce la directory delle tabelle e delle visualizzazioni Dynamics a livello principale.

Seleziona per visualizzare l’esempio di risposta

[
    {
        "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
    }
]

Utilizza la chiave primaria per ottimizzare l’esplorazione dei dati

NOTE

È possibile utilizzare attributi non di ricerca solo quando si utilizza l’approccio di chiave primaria per l’ottimizzazione.

È possibile ottimizzare le query di esplorazione fornendo primaryKey come parte dei parametri di query. Specificare la chiave primaria della tabella Dynamics quando si include primaryKey come parametro di query.

Formato API

GET /connections/{BASE_CONNECTION_ID}/explore?preview=true&object={OBJECT}&objectType={OBJECT_TYPE}&previewCount=10&primaryKey={PRIMARY_KEY}

Parametri della query

Descrizione

{BASE_CONNECTION_ID}

ID della connessione di base. Usa questo ID per esplorare il contenuto e la struttura dell’origine.

preview

Valore booleano che abilita l’anteprima dei dati.

{OBJECT}

L'oggetto Dynamics che si desidera esplorare.

{OBJECT_TYPE}

Tipo dell'oggetto.

previewCount

Restrizione che limita l’anteprima restituita a un determinato numero di record.

{PRIMARY_KEY}

Chiave primaria della tabella che si sta recuperando per l'anteprima.

Richiesta

Seleziona per visualizzare l’esempio di richiesta

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' \

Controllare la struttura di una tabella

Per verificare la struttura di una tabella specifica, eseguire una richiesta GET a /connections/{BASE_CONNECTION_ID}/explore e specificare il percorso della tabella specifica come parametro di query.

Formato API

GET /connections/{BASE_CONNECTION_ID}/explore?object={TABLE_PATH}&objectType=table

Parametro query

Descrizione

{BASE_CONNECTION_ID}

ID della connessione di base. Usa questo ID per esplorare il contenuto e la struttura dell’origine.

{TABLE_PATH}

Percorso della tabella specifica che si desidera esplorare.

Richiesta

La richiesta seguente recupera la struttura e il contenuto di una tabella Dynamics con percorso workflowdependency.

Seleziona per visualizzare l’esempio di richiesta

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' \

Risposta

In caso di esito positivo, la risposta restituisce il contenuto del percorso workflowdependency.

Seleziona per visualizzare l’esempio di risposta

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

Controllare la struttura di una vista

In Dynamics una visualizzazione si riferisce alle colonne da visualizzare, alla larghezza di ogni colonna, al sistema predefinito in cui viene ordinato un elenco di record e ai filtri predefiniti applicati per limitare i record da visualizzare nell'elenco.

Per verificare la struttura di una visualizzazione, effettuare una richiesta GET a /connections/{BASE_CONNECTION_ID}/explore e specificare il percorso di visualizzazione nei parametri di query. È inoltre necessario specificare objectType come view.

Formato API

GET /connections/{BASE_CONNECTION_ID}/explore?object={VIEW_PATH}&objectType=view

Parametro query

Descrizione

{BASE_CONNECTION_ID}

ID della connessione di base. Usa questo ID per esplorare il contenuto e la struttura dell’origine.

{VIEW_PATH}

Percorso della visualizzazione che si desidera controllare.

Richiesta

La richiesta seguente recupera accountView1.

Seleziona per visualizzare l’esempio di richiesta

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' \

Risposta

In caso di esito positivo, la risposta restituisce la struttura di accountView1.

Seleziona per visualizzare l’esempio di risposta

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

Anteprima vista tipo entità

Per visualizzare in anteprima il contenuto di una visualizzazione, effettuare una richiesta GET a /connections/{BASE_CONNECTION_ID}/explore e includere il percorso di visualizzazione e preview=true nei parametri di query.

Formato API

GET /connections/{BASE_CONNECTION_ID}/explore?object={VIEW_PATH}&preview=true&objectType=view

Parametro query

Descrizione

{BASE_CONNECTION_ID}

ID della connessione di base. Usa questo ID per esplorare il contenuto e la struttura dell’origine.

{VIEW_PATH}

Percorso della visualizzazione che si desidera controllare.

Richiesta

La richiesta seguente visualizza l'anteprima del contenuto di accountView1.

Seleziona per visualizzare l’esempio di richiesta

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' \

Risposta

Una risposta corretta restituisce il contenuto di accountView1.

Seleziona per visualizzare l’esempio di risposta

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

Creare una connessione sorgente per acquisire la vista

Per creare una connessione di origine e acquisire una visualizzazione, effettuare una richiesta POST all'endpoint /sourceConnections, fornire il nome della tabella e specificare entityType come view nel corpo della richiesta.

Formato API

POST /sourceConnections

Richiesta

La richiesta seguente crea una connessione di origine Dynamics e acquisisce le visualizzazioni.

Seleziona per visualizzare l’esempio di richiesta

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

Risposta

In caso di esito positivo, la risposta restituisce l’ID della connessione sorgente appena generato e il tag corrispondente.

Seleziona per visualizzare l’esempio di risposta

{
    "id": "e566bab3-1b58-428c-b751-86b8cc79a3b4",
    "etag": "\"82009592-0000-0200-0000-678121030000\""
}

Utilizza la chiave primaria per ottimizzare il flusso di dati

È inoltre possibile ottimizzare il flusso di dati Dynamics specificando la chiave primaria come parte dei parametri del corpo della richiesta.

Formato API

POST /sourceConnections

Richiesta

La richiesta seguente crea una connessione di origine Dynamics specificando la chiave primaria come contactid.

Seleziona per visualizzare l’esempio di richiesta

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

Proprietà

Descrizione

baseConnectionId

ID della connessione di base.

data.format

Il formato dei dati.

params.tableName

Nome della tabella in Dynamics.

params.primaryKey

Chiave primaria della tabella che ottimizzerà le query.

connectionSpec.id

ID della specifica di connessione corrispondente all'origine Dynamics.

Risposta

In caso di esito positivo, la risposta restituisce l’ID della connessione sorgente appena generato e il tag corrispondente.

Seleziona per visualizzare l’esempio di risposta

{
    "id": "e566bab3-1b58-428c-b751-86b8cc79a3b4",
    "etag": "\"82009592-0000-0200-0000-678121030000\""
}

Passaggi successivi

Seguendo questa esercitazione, è stata creata una connessione di base Microsoft Dynamics utilizzando l'API Flow Service. Puoi utilizzare questo ID connessione di base nelle seguenti esercitazioni:

recommendation-more-help