Configuración de la especificación de origen para orígenes de autoservicio (SDK por lotes)
Las especificaciones de la fuente contienen información específica de una fuente, incluidos los atributos pertenecientes a la categoría de una fuente, el estado beta y el icono de catálogo. También contienen información útil, como parámetros de URL, contenido, encabezado y programación. Las especificaciones de origen también describen el esquema de los parámetros necesarios para crear una conexión de origen a partir de una conexión base. El esquema es necesario para crear una conexión de origen.
Consulte la apéndice para ver un ejemplo de una especificación de origen completamente rellenada.
"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.",
"example": "https://{domain}.api.mailchimp.com"
},
"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": "The query parameters in json format",
}
},
"required": [
"host",
"path",
"method"
]
},
"headerParams": {
"type": "object",
"description": "The header parameters in json format",
},
"contentPath": {
"type": "object",
"description": "The parameters required for main collection content.",
"properties": {
"path": {
"description": "The path to the main content.",
"type": "string",
"example": "$.emails"
},
"skipAttributes": {
"type": "array",
"description": "The list of attributes that needs to be skipped while fattening the array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"keepAttributes": {
"type": "array",
"description": "The list of attributes that needs to be kept while fattening the array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"overrideWrapperAttribute": {
"type": "string",
"description": "The new name to be used for the root content path node.",
"example": "email"
}
},
"required": [
"path"
]
},
"explodeEntityPath": {
"type": "object",
"description": "The parameters required for the sub-array content.",
"properties": {
"path": {
"description": "The path to the sub-array content.",
"type": "string",
"example": "$.email.activity"
},
"skipAttributes": {
"type": "array",
"description": "The list of attributes that needs to be skipped while fattening sub-array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"keepAttributes": {
"type": "array",
"description": "The list of attributes that needs to be kept while fattening the sub-array.",
"example": "[total_items]",
"items": {
"type": "string"
}
},
"overrideWrapperAttribute": {
"type": "string",
"description": "The new name to be used for the root content path node.",
"example": "activity"
}
},
"required": [
"path"
]
},
"paginationParams": {
"type": "object",
"description": "The parameters required to fetch data using pagination.",
"properties": {
"type": {
"description": "The pagination fetch type.",
"type": "string",
"enum": [
"OFFSET",
"POINTER"
]
},
"limitName": {
"type": "string",
"description": "The limit property name",
"example": "limit or count"
},
"limitValue": {
"type": "integer",
"description": "The number of records to fetch per page.",
"example": "limit=10 or count=10"
},
"offsetName": {
"type": "string",
"description": "The offset property name",
"example": "offset"
},
"pointerPath": {
"type": "string",
"description": "The path to pointer property",
"example": "$.paging.next"
}
},
"required": [
"type",
"limitName",
"limitValue"
]
},
"scheduleParams": {
"type": "object",
"description": "The parameters required to fetch data for batch schedule.",
"properties": {
"scheduleStartParamName": {
"type": "string",
"description": "The order property name to get the order by date."
},
"scheduleEndParamName": {
"type": "string",
"description": "The order property name to get the order by date."
},
"scheduleStartParamFormat": {
"type": "string",
"description": "The order property name to get the order by date.",
"example": "yyyy-MM-ddTHH:mm:ssZ"
},
"scheduleEndParamFormat": {
"type": "string",
"description": "The order property name to get the order by date.",
"example": "yyyy-MM-ddTHH:mm:ssZ"
}
},
"required": [
"scheduleStartParamName",
"scheduleEndParamName"
]
}
},
"required": [
"urlParams",
"contentPath",
"paginationParams",
"scheduleParams"
]
}
},
}
sourceSpec.attributes
sourceSpec.attributes.uiAttributes
sourceSpec.attributes.uiAttributes.isBeta
true
false
sourceSpec.attributes.uiAttributes.category
advertising
crm
customer success
database
ecommerce
marketing automation
payments
protocols
sourceSpec.attributes.uiAttributes.icon
mailchimp-icon.svg
sourceSpec.attributes.uiAttributes.description
sourceSpec.attributes.uiAttributes.label
sourceSpec.attributes.spec.properties.urlParams
sourceSpec.attributes.spec.properties.urlParams.properties.path
/3.0/reports/${campaignId}/email-activity
sourceSpec.attributes.spec.properties.urlParams.properties.method
GET
, POST
sourceSpec.attributes.spec.properties.urlParams.properties.queryParams
${USER_PARAMETER}
."queryParams" : {"key" : "value", "key1" : "value1"}
se adjuntará a la dirección URL de origen como: /?key=value&key1=value1
sourceSpec.attributes.spec.properties.spec.properties.headerParams
"headerParams" : {"Content-Type" : "application/json", "x-api-key" : "key"}
sourceSpec.attributes.spec.properties.bodyParams
sourceSpec.attributes.spec.properties.contentPath
sourceSpec.attributes.spec.properties.contentPath.path
$.emails
sourceSpec.attributes.spec.properties.contentPath.skipAttributes
[total_items]
sourceSpec.attributes.spec.properties.contentPath.keepAttributes
[total_items]
sourceSpec.attributes.spec.properties.contentPath.overrideWrapperAttribute
contentPath
.email
sourceSpec.attributes.spec.properties.explodeEntityPath
sourceSpec.attributes.spec.properties.explodeEntityPath.path
$.email.activity
sourceSpec.attributes.spec.properties.explodeEntityPath.skipAttributes
[total_items]
sourceSpec.attributes.spec.properties.explodeEntityPath.keepAttributes
[total_items]
sourceSpec.attributes.spec.properties.explodeEntityPath.overrideWrapperAttribute
explodeEntityPath
.activity
sourceSpec.attributes.spec.properties.paginationParams
sourceSpec.attributes.spec.properties.paginationParams.type
OFFSET
: este tipo de paginación le permite analizar los resultados especificando un índice desde el que iniciar la matriz resultante y un límite en la cantidad de resultados devueltos.POINTER
: este tipo de paginación le permite utilizar unpointer
para que apunte a un elemento concreto que debe enviarse con una solicitud. La paginación de tipo de puntero requiere una ruta en la carga útil que dirija a la página siguiente.CONTINUATION_TOKEN
: este tipo de paginación le permite anexar los parámetros de consulta o encabezado con un token de continuación para recuperar los datos de retorno restantes de su origen, que no se devolvieron inicialmente debido a un máximo predeterminado.PAGE
: este tipo de paginación le permite anexar el parámetro de consulta con un parámetro de paginación para recorrer los datos devueltos por páginas, empezando por la página cero.NONE
: este tipo de paginación se puede utilizar para orígenes que no admiten ninguno de los tipos de paginación disponibles. Tipo de paginaciónNONE
devuelve todos los datos de respuesta después de una solicitud.
sourceSpec.attributes.spec.properties.paginationParams.limitName
limit
o count
sourceSpec.attributes.spec.properties.paginationParams.limitValue
limit=10
o count=10
sourceSpec.attributes.spec.properties.paginationParams.offSetName
offset
.offset
sourceSpec.attributes.spec.properties.paginationParams.pointerPath
pointer
.pointer
sourceSpec.attributes.spec.properties.scheduleParams
startTime
y endTime
, ambos le permiten establecer intervalos de tiempo específicos para ejecuciones por lotes, lo que garantiza que los registros recuperados en una ejecución por lotes anterior no se recuperen.sourceSpec.attributes.spec.properties.scheduleParams.scheduleStartParamName
since_last_changed
sourceSpec.attributes.spec.properties.scheduleParams.scheduleEndParamName
before_last_changed
sourceSpec.attributes.spec.properties.scheduleParams.scheduleStartParamFormat
scheduleStartParamName
.yyyy-MM-ddTHH:mm:ssZ
sourceSpec.attributes.spec.properties.scheduleParams.scheduleEndParamFormat
scheduleEndParamName
.yyyy-MM-ddTHH:mm:ssZ
sourceSpec.spec.properties
spec.properties
.Recursos adicionales appendix
En las siguientes secciones se proporciona información sobre las configuraciones adicionales que puede realizar para sourceSpec
, incluidos la programación avanzada y los esquemas personalizados.
Ejemplo de ruta de contenido content-path
A continuación se muestra un ejemplo del contenido de contentPath
propiedad en un MailChimp Members especificación de conexión.
"contentPath": {
"path": "$.members",
"skipAttributes": [
"_links",
"total_items",
"list_id"
],
"overrideWrapperAttribute": "member"
}
spec.properties
ejemplo de entrada de usuario user-input
El siguiente es un ejemplo de un archivo proporcionado por el usuario spec.properties
uso de un MailChimp Members especificación de conexión.
En este ejemplo, listId
se proporciona como parte de urlParams.path
. Si necesita recuperar listId
de un cliente, también debe definirlo como parte de spec.properties
.
"urlParams": {
"path": "/3.0/lists/${listId}/members",
"method": "GET"
}
"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."
}
}
}
Ejemplo de especificación de fuente source-spec
A continuación se muestra una especificación de origen completada utilizando MailChimp Members:
"sourceSpec": {
"attributes": {
"uiAttributes": {
"isSource": true,
"isPreview": true,
"isBeta": true,
"category": {
"key": "marketingAutomation"
},
"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"
},
"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."
}
}
}
}
Configurar diferentes tipos de paginación para el origen pagination
A continuación se muestran ejemplos de otros tipos de paginación admitidos por las fuentes de autoservicio (SDK por lotes):
Este tipo de paginación le permite analizar los resultados especificando un índice desde el que iniciar la matriz resultante y un límite en la cantidad de resultados devueltos. Por ejemplo:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
---|---|
Propiedad | Descripción |
type |
El tipo de paginación utilizado para devolver datos. |
limitName |
Nombre del límite a través del cual la API puede especificar el número de registros que se recuperarán en una página. |
limitValue |
El número de registros que se recuperarán en una página. |
offSetName |
Nombre del atributo de desplazamiento. Esto es necesario si el tipo de paginación está establecido en offset . |
endConditionName |
Un valor definido por el usuario que indica la condición que pondrá fin al bucle de paginación en la siguiente solicitud HTTP. Debe proporcionar el nombre del atributo en el que desea colocar la condición final. |
endConditionValue |
El valor del atributo en el que desea colocar la condición final. |
Este tipo de paginación le permite utilizar un pointer
para que apunte a un elemento concreto que debe enviarse con una solicitud. La paginación de tipo de puntero requiere una ruta en la carga útil que dirija a la página siguiente. Por ejemplo:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 | |
---|---|
Propiedad | Descripción |
type |
El tipo de paginación utilizado para devolver datos. |
limitName |
Nombre del límite a través del cual la API puede especificar el número de registros que se recuperarán en una página. |
limitValue |
El número de registros que se recuperarán en una página. |
pointerPath |
Nombre del atributo de puntero. Esto requiere una ruta json al atributo que señalará a la página siguiente. |
Un tipo de token de continuación de paginación devuelve un token de cadena que indica la existencia de más elementos que no se pudieron devolver, debido a un número máximo predeterminado de elementos que se pueden devolver en una sola respuesta.
Un origen que admite el tipo de token de continuación de paginación puede tener un parámetro de paginación similar al siguiente:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Propiedad | Descripción |
type |
El tipo de paginación utilizado para devolver datos. |
continuationTokenPath |
El valor que debe añadirse a los parámetros de consulta para pasar a la siguiente página de los resultados devueltos. |
parameterType |
El parameterType define dónde se encuentra la propiedad parameterName debe añadirse. El QUERYPARAM type le permite anexar la consulta con el parameterName . El HEADERPARAM le permite añadir su parameterName a su solicitud de encabezado. |
parameterName |
Nombre del parámetro utilizado para incorporar el token de continuación. El formato es el siguiente: {PARAMETER_NAME}={CONTINUATION_TOKEN} . |
delayRequestMillis |
El delayRequestMillis La propiedad en la paginación permite controlar la velocidad de las solicitudes realizadas al origen. Algunas fuentes pueden tener un límite en la cantidad de solicitudes que se pueden realizar por minuto. Por ejemplo, Zendesk tiene un límite de 100 solicitudes por minuto y define delayRequestMillis hasta 850 permite configurar el origen para realizar llamadas a solo alrededor de 80 solicitudes por minuto, muy por debajo del umbral de 100 solicitudes por minuto. |
El siguiente es un ejemplo de una respuesta devuelta mediante el tipo de token de continuación de paginación:
code language-json |
---|
|
El PAGE
El tipo de paginación le permite recorrer los datos devueltos en función del número de páginas a partir de cero. Al utilizar PAGE
Para la paginación de tipo, debe proporcionar el número de registros dados en una sola página.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 layout-auto | |
---|---|
Propiedad | Descripción |
type |
El tipo de paginación utilizado para devolver datos. |
limitName |
Nombre del límite a través del cual la API puede especificar el número de registros que se recuperarán en una página. |
limitValue |
El número de registros que se recuperarán en una página. |
initialPageIndex |
(Opcional) El índice de página inicial define el número de página desde el que se iniciará la paginación. Este campo se puede utilizar para orígenes en los que la paginación no comienza desde 0. Si no se proporciona, el índice de página inicial se establecerá de forma predeterminada en 0. Este campo espera un entero. |
endPageIndex |
(Opcional) El índice de página final permite establecer una condición final y detener la paginación. Este campo se puede utilizar cuando las condiciones de finalización predeterminadas para detener la paginación no están disponibles. Este campo también se puede utilizar si el número de páginas que se van a introducir o el último número de página se proporcionan a través del encabezado de respuesta, que es común al utilizar PAGE escriba paginación. El valor del índice de página final puede ser el último número de página o un valor de expresión de tipo cadena del encabezado de respuesta. Por ejemplo, puede utilizar headers.x-pagecount para asignar un índice de página final a x-pagecount valor de los encabezados de respuesta. Nota: x-pagecount es un encabezado de respuesta obligatorio para algunas fuentes y contiene el valor número de páginas que se van a introducir. |
pageParamName |
Nombre del parámetro que debe anexar a los parámetros de consulta para recorrer diferentes páginas de los datos devueltos. Por ejemplo, https://abc.com?pageIndex=1 devolvería la segunda página de la carga útil devuelta de una API. |
maximumRequest |
Número máximo de solicitudes que un origen puede realizar para una ejecución incremental determinada. El límite predeterminado actual es 10000. |
El NONE
el tipo de paginación se puede utilizar para orígenes que no admiten ninguno de los tipos de paginación disponibles. Orígenes que utilizan el tipo de paginación de NONE
simplemente devuelva todos los registros recuperables cuando se realice una solicitud de GET.
code language-json |
---|
|
Programación avanzada de orígenes de autoservicio (SDK por lotes)
Configure la programación incremental y de relleno del origen mediante la programación avanzada. El incremental
permite configurar una programación en la que el origen solo ingestará registros nuevos o modificados, mientras que la propiedad backfill
La propiedad permite crear una programación para introducir datos históricos.
Con la programación avanzada, puede utilizar expresiones y funciones específicas del origen para configurar programaciones incrementales y de relleno. En el ejemplo siguiente, la variable Zendesk El origen requiere que la programación incremental tenga el formato type:user updated > {START_TIME} updated < {END_TIME}
y relleno como type:user updated < {END_TIME}
.
"scheduleParams": {
"type": "ADVANCE",
"paramFormat": "yyyy-MM-ddTHH:mm:ssK",
"incremental": "type:user updated > {START_TIME} updated < {END_TIME}",
"backfill": "type:user updated < {END_TIME}"
}
scheduleParams.type
ADVANCE
para utilizar el tipo de programación avanzada.scheduleParams.paramFormat
scheduleStartParamFormat
y scheduleEndParamFormat
valores.scheduleParams.incremental
scheduleParams.backfill
Una vez configurada la programación avanzada, debe consultar la scheduleParams
en la sección URL, body o header params, según lo que admita la fuente concreta. En el ejemplo siguiente, {SCHEDULE_QUERY}
es un marcador de posición que se utiliza para especificar dónde se utilizarán las expresiones de programación incremental y de relleno. En el caso de un Zendesk origen, query
se utiliza en la queryParams
para especificar la programación avanzada.
"urlParams": {
"path": "/api/v2/search/export@{if(empty(coalesce(pipeline()?.parameters?.ingestionStart,'')),'?query=type:user&filter[type]=user&','')}",
"method": "GET",
"queryParams": {
"query": "{SCHEDULE_QUERY}",
"filter[type]": "user"
}
}
Añada un esquema personalizado para definir los atributos dinámicos del origen
Puede incluir un esquema personalizado en su sourceSpec
para definir todos los atributos necesarios para el origen, incluidos los atributos dinámicos que pueda necesitar. Puede actualizar la especificación de conexión correspondiente del origen realizando una solicitud del PUT al /connectionSpecs
punto final del Flow Service API, mientras proporciona su esquema personalizado en la sourceSpec
de la especificación de conexión.
A continuación se muestra un ejemplo de esquema personalizado que puede agregar a la especificación de conexión del origen:
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"organization_id": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
}
"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"
}
}
}
}
}
}
}
Pasos siguientes
Una vez rellenadas las especificaciones de origen, puede continuar con la configuración de las especificaciones de exploración del origen que desea integrar en Platform. Consulte el documento sobre configuración de especificaciones de exploración para obtener más información.