Connetti Zendesk ad Experience Platform utilizzando l'API Flow Service
Il seguente tutorial illustra i passaggi necessari per creare una connessione di origine Zendesk e un flusso di dati per portare dati Zendesk in Experience Platform utilizzando l'Flow Service API.
Creare una 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 di connessione di base, eseguire una richiesta POST all'endpoint /connections fornendo le credenziali di autenticazione Zendesk come parte del corpo della richiesta.
Formato API
POST /connections
Richiesta
La richiesta seguente crea una connessione di base per Zendesk:
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Zendesk base connection",
"description": "Zendesk base connection to authenticate to Experience Platform",
"connectionSpec": {
"id": "0a27232b-2c6e-4396-b8c6-c9fc24e37ba4",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Refresh Code",
"params": {
"subdomain": "{SUBDOMAIN}",
"accessToken": "{ACCESS_TOKEN}"
}
}
}'
| Proprietà | Descrizione |
|---|---|
name | Nome della connessione di base. Verificare che il nome della connessione di base sia descrittivo, in quanto è possibile utilizzarlo per cercare informazioni sulla connessione di base. |
description | Valore facoltativo che è possibile includere per fornire ulteriori informazioni sulla connessione di base. |
connectionSpec.id | ID della specifica di connessione dell'origine. Questo ID può essere recuperato dopo che l'origine è stata registrata e approvata tramite l'API Flow Service. |
auth.specName | Tipo di autenticazione utilizzato per autenticare l’origine in Experience Platform. |
auth.params. | Contiene le credenziali necessarie per autenticare l’origine. |
auth.params.subdomain | Il dominio univoco associato al tuo account. Il formato del sottodominio è https://yoursubdomain.zendesk.com. |
auth.params.accessToken | Il token di accesso corrispondente utilizzato per autenticare l’origine. Questo è richiesto per l’autenticazione basata su OAuth. |
Risposta
In caso di esito positivo, la risposta restituisce la connessione di base appena creata, incluso il relativo identificatore univoco di connessione (id). Questo ID è necessario per esplorare la struttura e il contenuto del file sorgente nel passaggio successivo.
{
"id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}
Esplora l’origine
Utilizzando l’ID connessione di base generato nel passaggio precedente, puoi esplorare file e directory eseguendo le richieste di GET.
Utilizzare le seguenti chiamate per trovare il percorso del file che si desidera inserire in Experience Platform:
Formato API
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Quando esegui le richieste di GET per esplorare la struttura e il contenuto dei file dell’origine, devi includere i parametri di query elencati nella tabella seguente:
| Parametro | Descrizione |
|---|---|
{BASE_CONNECTION_ID} | ID della connessione di base generato nel passaggio precedente. |
objectType=rest | Tipo di oggetto che si desidera esplorare. Attualmente, questo valore è sempre impostato su rest. |
{OBJECT} | Questo parametro è necessario solo quando si visualizza una directory specifica. Il relativo valore rappresenta il percorso della directory che desideri esplorare. |
fileType=json | Il tipo di file che desideri portare in Experience Platform. Attualmente, json è l'unico tipo di file supportato. |
{PREVIEW} | Valore booleano che definisce se il contenuto della connessione supporta l’anteprima. |
{SOURCE_PARAMS} | Definisce i parametri per il file di origine che desideri portare in Experience Platform. Per recuperare il formato accettato per {SOURCE_PARAMS}, è necessario codificare l'intera stringa parameter in base64. Nell'esempio seguente, "{}" codificato in base64 equivale a e30. |
Richiesta
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/70383d02-2777-4be7-a309-9dd6eea1b46d/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=e30' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
In caso di esito positivo, la risposta restituisce la struttura del file su cui è stata eseguita la query. Nell'esempio seguente nel payload data[] viene visualizzato un solo record, tuttavia potrebbero essere presenti più record.
{
"format": "hierarchical",
"schema": {
"type": "object",
"properties": {
"result": {
"type": "object",
"properties": {
"organization_id": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
},
"external_id": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
},
"role_type": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
},
"custom_role_id": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
},
"default_group_id": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
},
"phone": {
"type": "string"
},
"shared_phone_number": {
"type": "boolean"
},
"alias": {
"type": "string"
},
"last_login_at": {
"type": "string"
},
"signature": {
"type": "string"
},
"details": {
"type": "string"
},
"notes": {
"type": "string"
},
"photo": {
"type": "string",
"media": {
"binaryEncoding": "base64",
"type": "image/png"
}
},
"active": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"email": {
"type": "string"
},
"iana_time_zone": {
"type": "string"
},
"id": {
"type": "integer"
},
"locale": {
"type": "string"
},
"locale_id": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": "string"
},
"only_private_comments": {
"type": "boolean"
},
"report_csv": {
"type": "boolean"
},
"restricted_agent": {
"type": "boolean"
},
"result_type": {
"type": "string"
},
"role": {
"type": "integer"
},
"shared": {
"type": "boolean"
},
"shared_agent": {
"type": "boolean"
},
"suspended": {
"type": "boolean"
},
"ticket_restriction": {
"type": "string"
},
"time_zone": {
"type": "string"
},
"two_factor_auth_enabled": {
"type": "boolean"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"data": [
{
"result": {
"id": 6106699702801,
"url": "https://{YOURSUBDOMAIN}.zendesk.com/api/v2/users/6106699702801.json",
"name": "test",
"email": "test@org.com",
"created_at": "2022-05-13T08:04:22Z",
"updated_at": "2022-05-13T08:04:22Z",
"time_zone": "Asia/Kolkata",
"iana_time_zone": "Asia/Kolkata",
"locale_id": 1,
"locale": "en-US",
"role": "end-user",
"verified": false,
"active": true,
"shared": false,
"shared_agent": false,
"two_factor_auth_enabled": false,
"moderator": false,
"ticket_restriction": "requested",
"only_private_comments": false,
"restricted_agent": true,
"suspended": false,
"report_csv": false,
"result_type": "user"
}
}
]
}
Creare una connessione sorgente
È possibile creare una connessione di origine effettuando una richiesta POST all'API Flow Service. Una connessione di origine è costituita da un ID di connessione, un percorso del file di dati di origine e un ID della specifica di connessione.
Formato API
POST /sourceConnections
Richiesta
La richiesta seguente crea una connessione di origine per Zendesk:
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Zendesk Source Connection",
"description": "Zendesk Source Connection",
"baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"connectionSpec": {
"id": "0a27232b-2c6e-4396-b8c6-c9fc24e37ba4",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {}
}'
| Proprietà | Descrizione |
|---|---|
name | Nome della connessione di origine. Assicurati che il nome della connessione sorgente sia descrittivo, in quanto può essere utilizzato per cercare informazioni sulla connessione sorgente. |
description | Valore facoltativo che è possibile includere per fornire ulteriori informazioni sulla connessione di origine. |
baseConnectionId | ID connessione di base di Zendesk. Questo ID è stato generato in un passaggio precedente. |
connectionSpec.id | ID della specifica di connessione corrispondente all'origine. |
data.format | Formato dei dati Zendesk che si desidera acquisire. Attualmente, l'unico formato di dati supportato è json. |
Risposta
In caso di esito positivo, la risposta restituisce l'identificatore univoco (id) della connessione di origine appena creata. Questo ID è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}