Skapa en ny anslutningsspecifikation med API:t Flow Service
En anslutningsspecifikation representerar strukturen för en källa. Den innehåller information om en källas autentiseringskrav, definierar hur källdata kan utforskas och inspekteras samt ger information om attributen för en viss källa. Med slutpunkten /connectionSpecs i API:t Flow Service kan du programmässigt hantera anslutningsspecifikationerna inom organisationen.
I följande dokument beskrivs hur du skapar en anslutningsspecifikation med hjälp av API:t Flow Service och integrerar en ny källa med självbetjäningskällor (Batch SDK).
Komma igång
Innan du fortsätter bör du läsa kom igång-guiden för att få länkar till relaterad dokumentation, en guide till hur du läser exempelanropen för API i det här dokumentet och viktig information om vilka huvuden som krävs för att kunna anropa ett Experience Platform-API.
Samla in artefakter
Om du vill skapa en ny batchkälla med hjälp av självbetjäningskällor måste du först koordinera med Adobe, begära en privat Git-databas och anpassa dig till Adobe om källans etikett, beskrivning, kategori och ikon.
När du har angett den måste du strukturera din privata Git-databas så här:
-
Källor
-
-
Artefakter
- {your_source}-category.txt
- {your_source}-description.txt
- {your_source}-icon.svg
- {your_source}-label.txt
- {your_source}-connectionSpec.json
-
-
Artefakter (filnamn)
Beskrivning
Exempel
Namnet på källan. Den här mappen bör innehålla alla artefakter som hör till källan i din privata Git-databas.
mailchimp-members{your_source}-category.txt
Kategorin som källan tillhör, formaterad som en textfil. En lista över tillgängliga källkategorier som stöds av självbetjäningskällor (Batch SDK) är:
- Advertising
- Analytics
- Samtycke och inställningar
- CRM
- Nöjda kunder
- Databas
- e-Commerce
- Marknadsföringsautomatisering
- Betalningar
- Protokoll
Obs! Om du tror att din källa inte passar in i någon av ovanstående kategorier kan du kontakta din Adobe-representant för att diskutera saken.
mailchimp-members-category.txt Ange källkategorin i filen, till exempel: marketingAutomation.{your_source}-description.txt
En kort beskrivning av källan.
Mailchimp Members är en källa för automatiserad marknadsföring som du kan använda för att hämta Mailchimp Members-data till Experience Platform.
{your_source}-icon.svg
Bilden som ska användas för att representera källan i katalogen för Experience Platform-källor. Den här ikonen måste vara en SVG-fil.
{your_source}-label.txt
Källans namn så som det ska visas i katalogen Experience Platform sources.
Mailchimp-medlemmar
{your_source}-connectionSpec.json
En JSON-fil som innehåller anslutningsspecifikationen för källan. Den här filen behövs inte från början eftersom du fyller i anslutningsspecifikationen när du slutför den här guiden.
mailchimp-members-connectionSpec.jsonTIP
Under testperioden för anslutningsspecifikationen kan du i stället för nyckelvärden använda
text i anslutningsspecifikationen.När du har lagt till de nödvändiga filerna i din privata Git-databas måste du skapa en pull-begäran (PR) som Adobe kan granska. När din PR har godkänts och sammanfogats får du ett ID som kan användas för din anslutningsspecifikation för att hänvisa till källans etikett, beskrivning och ikon.
Följ sedan stegen som beskrivs nedan för att konfigurera anslutningsspecifikationen. Mer information om olika funktioner som du kan lägga till i källan, till exempel avancerad schemaläggning, anpassat schema eller olika sidnumreringstyper, finns i guiden Konfigurera källspecifikationer.
Kopiera mall för anslutningsspecifikation
När du har samlat in de nödvändiga artefakterna kopierar och klistrar du in mallen för anslutningsspecifikation nedan i valfri textredigerare och uppdaterar sedan attributen inom hakparenteser {} med information som är relevant för just din källa.
{
"name": "generic-rest-extension",
"type": "generic-rest",
"description": "{DESCRIPTION}",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"attributes": {
"uiAttributes": {
"apiFeatures": {
"explorePaginationSupported": false
}
}
},
"authSpec": [
{
"name": "OAuth2 Refresh Code",
"type": "OAuth2RefreshCode",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "Define auth params required for connecting to generic rest using oauth2 authorization code.",
"properties": {
"authorizationTestUrl": {
"description": "Authorization test url to validate accessToken.",
"type": "string"
},
"clientId": {
"description": "Client id of user account.",
"type": "string"
},
"clientSecret": {
"description": "Client secret of user account.",
"type": "string",
"format": "password"
},
"accessToken": {
"description": "Access Token",
"type": "string",
"format": "password"
},
"refreshToken": {
"description": "Refresh Token",
"type": "string",
"format": "password"
},
"expirationDate": {
"description": "Date of token expiry.",
"type": "string",
"format": "date",
"uiAttributes": {
"hidden": true
}
},
"accessTokenUrl": {
"description": "Access token url to fetch access token.",
"type": "string"
},
"requestParameterOverride": {
"type": "object",
"description": "Specify parameter to override.",
"properties": {
"accessTokenField": {
"description": "Access token field name to override.",
"type": "string"
},
"refreshTokenField": {
"description": "Refresh token field name to override.",
"type": "string"
},
"expireInField": {
"description": "ExpireIn field name to override.",
"type": "string"
},
"authenticationMethod": {
"description": "Authentication method override.",
"type": "string",
"enum": [
"GET",
"POST"
]
},
"clientId": {
"description": "ClientId field name override.",
"type": "string"
},
"clientSecret": {
"description": "ClientSecret field name override.",
"type": "string"
}
}
}
},
"required": [
"host",
"accessToken"
]
}
},
{
"name": "Basic Authentication",
"type": "BasicAuthentication",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines auth params required for connecting to rest service.",
"properties": {
"host": {
"type": "string",
"description": "Enter resource url host path"
},
"username": {
"description": "Username to connect rest endpoint.",
"type": "string"
},
"password": {
"description": "Password to connect rest endpoint.",
"type": "string",
"format": "password"
}
},
"required": [
"host",
"username",
"password"
]
}
}
],
"sourceSpec": {
"attributes": {
"uiAttributes": {
"isSource": true,
"isPreview": true,
"isBeta": true,
"category": {
"key": "protocols"
},
"icon": {
"key": "genericRestIcon"
},
"description": {
"key": "genericRestDescription"
},
"label": {
"key": "genericRestLabel"
}
}
},
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines static and user input parameters to fetch resource values.",
"properties": {
"urlParams": {
"type": "object",
"properties": {
"host": {
"type": "string",
"description": "Enter resource url host path."
},
"path": {
"type": "string",
"description": "Enter resource path",
"example": "/3.0/reports/campaignId/email-activity"
},
"method": {
"type": "string",
"description": "Http method type.",
"enum": [
"GET",
"POST"
]
},
"queryParams": {
"type": "object",
"description": "query parameters in json format",
"example": "{'key':'value','key1':'value1'} in JSON format"
}
},
"required": [
"path",
"method"
]
},
"headerParams": {
"type": "object",
"description": "header parameters in json format",
"example": "{'user':'c26f50c88dc035610e6753f807e28e9','x-api-key':'apiKey'}"
},
"contentPath": {
"type": "object",
"description": "Params required for main collection content.",
"properties": {
"path": {
"description": "path to main content.",
"type": "string",
"example": "$.emails"
},
"skipAttributes": {
"type": "array",
"description": "list of attributes that needs to be skipped while fattening the array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"keepAttributes": {
"type": "array",
"description": "list of attributes that needs to be kept while fattening the array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"overrideWrapperAttribute": {
"type": "string",
"description": "rename root content path node.",
"example": "email"
}
},
"required": [
"path"
]
},
"explodeEntityPath": {
"type": "object",
"description": "Params required for sub-array content.",
"properties": {
"path": {
"description": "path to sub-array content.",
"type": "string",
"example": "$.email.activity"
},
"skipAttributes": {
"type": "array",
"description": "list of attributes that needs to be skipped while fattening sub-array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"keepAttributes": {
"type": "array",
"description": "list of attributes that needs to be kept while fattening the sub-array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"overrideWrapperAttribute": {
"type": "string",
"description": "rename root content path node.",
"example": "activity"
}
},
"required": [
"path"
]
},
"paginationParams": {
"type": "object",
"description": "Params required to fetch data using pagination.",
"properties": {
"type": {
"description": "Pagination fetch type.",
"type": "string",
"enum": [
"OFFSET",
"POINTER"
]
},
"limitName": {
"type": "string",
"description": "limit property name",
"example": "limit or count"
},
"limitValue": {
"type": "integer",
"description": "number of records per page to fetch.",
"example": "limit=10 or count=10"
},
"offsetName": {
"type": "string",
"description": "offset property name",
"example": "offset"
},
"pointerPath": {
"type": "string",
"description": "pointer property name",
"example": "pointer"
}
},
"required": [
"type",
"limitName",
"limitValue"
]
},
"scheduleParams": {
"type": "object",
"description": "Params required to fetch data for batch schedule.",
"properties": {
"scheduleStartParamName": {
"type": "string",
"description": "order property name to get the order by date."
},
"scheduleEndParamName": {
"type": "string",
"description": "order property name to get the order by date."
},
"scheduleStartParamFormat": {
"type": "string",
"description": "order property name to get the order by date.",
"example": "yyyy-MM-ddTHH:mm:ssZ"
},
"scheduleEndParamFormat": {
"type": "string",
"description": "order property name to get the order by date.",
"example": "yyyy-MM-ddTHH:mm:ssZ"
}
},
"required": [
"scheduleStartParamName",
"scheduleEndParamName"
]
}
},
"required": [
"urlParams",
"contentPath",
"paginationParams",
"scheduleParams"
]
}
},
"exploreSpec": {
"name": "Resource",
"type": "Resource",
"requestSpec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object"
},
"responseSpec": {
"$schema": "http: //json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"format": {
"type": "string"
},
"schema": {
"type": "object",
"properties": {
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
Skapa en anslutningsspecifikation create
När du har skaffat en mall för anslutningsspecifikation kan du nu börja skapa en ny anslutningsspecifikation genom att fylla i de värden som motsvarar källan.
En anslutningsspecifikation kan delas in i tre olika delar: autentiseringsspecifikationerna, källspecifikationerna och undersökningsspecifikationerna.
I följande dokument finns instruktioner om hur du fyller i värdena för varje del av en anslutningsspecifikation:
Med din specifikationsinformation uppdaterad kan du skicka den nya anslutningsspecifikationen genom att göra en POST-förfrågan till /connectionSpecs-slutpunkten för Flow Service API.
API-format
POST /connectionSpecs
Begäran
Följande begäran är ett exempel på en fullständigt skriven anslutningsspecifikation för en MailChimp-källa:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
-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": "MailChimp Members source",
"description": "MailChimp Members source using generic-rest and SDK",
"type": "generic-rest",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"attributes": {
"uiAttributes": {
"apiFeatures": {
"explorePaginationSupported": false
}
}
},
"authSpec": [
{
"name": "OAuth2 Refresh Code",
"type": "OAuth2RefreshCode",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "Define auth params required for connecting to generic rest using oauth2 authorization code.",
"properties": {
"domain": {
"type": "string",
"description": "Enter domain name for host url"
},
"authorizationTestUrl": {
"description": "Authorization test url to validate accessToken.",
"type": "string"
},
"accessToken": {
"description": "Access Token of mailChimp endpoint.",
"type": "string",
"format": "password"
}
},
"required": [
"domain",
"accessToken"
]
}
},
{
"name": "Basic Authentication",
"type": "BasicAuthentication",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines auth params required for connecting to rest service.",
"properties": {
"domain": {
"type": "string",
"description": "Enter domain name for host url"
},
"username": {
"description": "Username to connect mailChimp endpoint.",
"type": "string"
},
"password": {
"description": "Password to connect mailChimp endpoint.",
"type": "string",
"format": "password"
}
},
"required": [
"domain",
"username",
"password"
]
}
}
],
"sourceSpec": {
"attributes": {
"uiAttributes": {
"isSource": true,
"isPreview": true,
"isBeta": true,
"icon": {
"key": "mailchimpMembersIcon"
},
"description": {
"key": "mailchimpMembersDescription"
},
"label": {
"key": "mailchimpMembersLabel"
}
},
"urlParams": {
"host": "https://${domain}.api.mailchimp.com",
"path": "/3.0/lists/${listId}/members",
"method": "GET"
},
"contentPath": {
"path": "$.members",
"skipAttributes": [
"_links",
"total_items",
"list_id"
],
"overrideWrapperAttribute": "member"
},
"paginationParams": {
"type": "OFFSET",
"limitName": "count",
"limitValue": "100",
"offSetName": "offset",
"endConditionName": "$.hasMore",
"endConditionValue": "Const:false"
},
"scheduleParams": {
"scheduleStartParamName": "since_last_changed",
"scheduleEndParamName": "before_last_changed",
"scheduleStartParamFormat": "yyyy-MM-ddTHH:mm:ss:fffffffK",
"scheduleEndParamFormat": "yyyy-MM-ddTHH:mm:ss:fffffffK"
}
},
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "Define user input parameters to fetch resource values.",
"properties": {
"listId": {
"type": "string",
"description": "listId for which members need to fetch."
}
}
}
},
"exploreSpec": {
"name": "Resource",
"type": "Resource",
"requestSpec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object"
},
"responseSpec": {
"$schema": "http: //json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"format": {
"type": "string"
},
"schema": {
"type": "object",
"properties": {
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}'
Svar
Ett lyckat svar returnerar den nyligen skapade anslutningsspecifikationen, inklusive dess unika id.
{
"id": "f6c0de0c-0a42-4cd9-9139-8768bf2f1b55",
"createdAt": 1633388930134,
"updatedAt": 1633388930134,
"createdBy": "{CREATED_BY}",
"updatedBy": "{UPDATED_BY}",
"createdClient": "{CREATED_CLIENT}",
"updatedClient": "{UPDATED_CLIENT}",
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"imsOrgId": "{ORG_ID}",
"name": "MailChimp Members source",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"type": "generic-rest",
"authSpec": [
{
"name": "OAuth2 Refresh Code",
"type": "OAuth2RefreshCode",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "Define auth params required for connecting to generic rest using oauth2 authorization code.",
"properties": {
"host": {
"type": "string",
"description": "Enter resource url host path"
},
"authorizationTestUrl": {
"description": "Authorization test url to validate accessToken.",
"type": "string"
},
"accessToken": {
"description": "Access Token of mailChimp endpoint.",
"type": "string",
"format": "password"
}
},
"required": [
"host",
"accessToken"
]
}
},
{
"name": "Basic Authentication",
"type": "BasicAuthentication",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines auth params required for connecting to rest service.",
"properties": {
"host": {
"type": "string",
"description": "Enter resource url host path."
},
"username": {
"description": "Username to connect mailChimp endpoint.",
"type": "string"
},
"password": {
"description": "Password to connect mailChimp endpoint.",
"type": "string",
"format": "password"
}
},
"required": [
"host",
"username",
"password"
]
}
}
],
"sourceSpec": {
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "Define user input parameters to fetch resource values.",
"properties": {
"listId": {
"type": "string",
"description": "listId for which members need to fetch."
}
}
},
"attributes": {
"uiAttributes": {
"isSource": true,
"isPreview": true,
"isBeta": true,
"icon": {
"key": "mailchimpMembersIcon"
},
"description": {
"key": "mailchimpMembersDescription"
},
"label": {
"key": "mailchimpMembersLabel"
}
},
"urlParams": {
"path": "/3.0/lists/${listId}/members",
"method": "GET"
},
"contentPath": {
"path": "$.members",
"skipAttributes": [
"_links",
"total_items",
"list_id"
],
"overrideWrapperAttribute": "member"
},
"paginationParams": {
"type": "OFFSET",
"limitName": "count",
"limitValue": "100",
"offSetName": "offset",
"endConditionName": "$.hasMore",
"endConditionValue": "Const:false"
},
"scheduleParams": {
"scheduleStartParamName": "since_last_changed",
"scheduleEndParamName": "before_last_changed",
"scheduleStartParamFormat": "yyyy-MM-ddTHH:mm:ss:fffffffK",
"scheduleEndParamFormat": "yyyy-MM-ddTHH:mm:ss:fffffffK"
}
}
},
"exploreSpec": {
"name": "Resource",
"type": "Resource",
"requestSpec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object"
},
"responseSpec": {
"$schema": "http: //json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"format": {
"type": "string"
},
"schema": {
"type": "object",
"properties": {
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
},
"attributes": {
"uiAttributes": {
"apiFeatures": {
"explorePaginationSupported": false
}
}
}
}
Nästa steg
Nu när du har skapat en ny anslutningsspecifikation måste du lägga till dess motsvarande anslutningsspecifikation-ID till en befintlig flödesspecifikation. Mer information finns i självstudiekursen Uppdatera flödesspecifikationer.
Om du vill ändra anslutningsspecifikationen som du har skapat kan du läsa självstudiekursen om att uppdatera anslutningsspecifikationerna.
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089