DocumentazioneExperience PlatformGuida ai connettori di origini

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

Last update: Mon Feb 17 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 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 di Platform.
  • Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.

Utilizzo delle API di Platform

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

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per connettere correttamente 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
table 0-row-2 1-row-2 2-row-2 3-row-2
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
table 0-row-2 1-row-2 2-row-2
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.

accordion
Seleziona per visualizzare l’esempio di richiesta
code language-shell 
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"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
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).

accordion
Seleziona per visualizzare l’esempio di risposta
code language-json 
{
    "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.

accordion
Seleziona per visualizzare l’esempio di richiesta
code language-shell 
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"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
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).

accordion
Seleziona per visualizzare l’esempio di risposta
code language-json 
{
    "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
code language-shell 
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
code language-json 
[
    {
        "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
    }
]

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
code language-shell 
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
code language-json 
{
    "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
code language-shell 
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
code language-json 
{
    "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
code language-shell 
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
code language-json 
{
    "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
code language-shell 
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
code language-json 
{
    "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
337b99bb-92fb-42ae-b6b7-c7042161d089