Configurar especificação de origem para Origens de Autoatendimento (SDK em Lote)
As especificações do Source contêm informações específicas de uma origem, incluindo atributos pertencentes à categoria de uma origem, status beta e ícone de catálogo. Eles também contêm informações úteis, como parâmetros de URL, conteúdo, cabeçalho e agendamento. As especificações do Source também descrevem o esquema dos parâmetros necessários para criar uma conexão de origem a partir de uma conexão de base. O esquema é necessário para criar uma conexão de origem.
Consulte o apêndice para obter um exemplo de uma especificação de origem totalmente preenchida.
"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"}
será anexado à URL de origem 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
: esse tipo de paginação permite analisar os resultados especificando um índice de onde iniciar a matriz resultante e um limite para quantos resultados são retornados.POINTER
: Esse tipo de paginação permite que você use uma variávelpointer
para apontar para um item específico que precisa ser enviado com uma solicitação. A paginação de tipo de ponteiro requer um caminho na carga que aponte para a próxima página.CONTINUATION_TOKEN
: esse tipo de paginação permite anexar seus parâmetros de consulta ou cabeçalho a um token de continuação para recuperar os dados de retorno restantes de sua origem, que não foram retornados inicialmente devido a um máximo predeterminado.PAGE
: esse tipo de paginação permite que você anexe seu parâmetro de consulta com um parâmetro de paginação para percorrer os dados de retorno por páginas, começando da página zero.NONE
: Esse tipo de paginação pode ser usado para fontes que não oferecem suporte a nenhum dos tipos de paginação disponíveis. O tipo de paginaçãoNONE
retorna todos os dados de resposta após uma solicitação.
sourceSpec.attributes.spec.properties.paginationParams.limitName
limit
ou count
sourceSpec.attributes.spec.properties.paginationParams.limitValue
limit=10
ou count=10
sourceSpec.attributes.spec.properties.paginationParams.offSetName
offset
.offset
sourceSpec.attributes.spec.properties.paginationParams.pointerPath
pointer
.pointer
sourceSpec.attributes.spec.properties.scheduleParams
startTime
e endTime
, que permitem definir intervalos de tempo específicos para execuções em lote, o que garante que os registros buscados em uma execução em lote anterior não sejam buscados novamente.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 adicionais appendix
As seções a seguir fornecem informações sobre as configurações adicionais que você pode fazer no sourceSpec
, incluindo o agendamento avançado e esquemas personalizados.
Exemplo de caminho de conteúdo content-path
Este é um exemplo do conteúdo da propriedade contentPath
em uma especificação de conexão MailChimp Members.
"contentPath": {
"path": "$.members",
"skipAttributes": [
"_links",
"total_items",
"list_id"
],
"overrideWrapperAttribute": "member"
}
spec.properties
exemplo de entrada de usuário user-input
Veja a seguir um exemplo de um spec.properties
fornecido pelo usuário usando uma especificação de conexão MailChimp Members.
Neste exemplo, listId
é fornecido como parte de urlParams.path
. Se você precisar recuperar listId
de um cliente, defina-o também 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."
}
}
}
Exemplo de especificação do Source source-spec
Esta é uma especificação de origem concluída usando 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 tipos de paginação diferentes para a origem pagination
A seguir estão exemplos de outros tipos de paginação compatíveis com Origens de Autoatendimento (SDK em lote):
Esse tipo de paginação permite analisar os resultados especificando um índice de onde iniciar o array resultante e um limite para quantos resultados são retornados. Por exemplo:
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 | |
---|---|
Propriedade | Descrição |
type |
O tipo de paginação usado para retornar dados. |
limitName |
O nome do limite pelo qual a API pode especificar o número de registros a serem buscados em uma página. |
limitValue |
O número de registros a serem buscados em uma página. |
offSetName |
O nome do atributo offset. Isso é necessário se o tipo de paginação for definido como offset . |
endConditionName |
Um valor definido pelo usuário que indica a condição que encerrará o loop de paginação na próxima solicitação HTTP. Você deve fornecer o nome do atributo no qual deseja colocar a condição final. |
endConditionValue |
O valor do atributo no qual você deseja colocar a condição final. |
Esse tipo de paginação permite usar uma variável pointer
para apontar para um item específico que precisa ser enviado com uma solicitação. A paginação de tipo de ponteiro requer um caminho na carga que aponte para a próxima página. Por exemplo:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 | |
---|---|
Propriedade | Descrição |
type |
O tipo de paginação usado para retornar dados. |
limitName |
O nome do limite pelo qual a API pode especificar o número de registros a serem buscados em uma página. |
limitValue |
O número de registros a serem buscados em uma página. |
pointerPath |
O nome do atributo de ponteiro. Isso requer o caminho json para o atributo que apontará para a próxima página. |
Um tipo de token de continuação de paginação retorna um token de sequência de caracteres que significa a existência de mais itens que não puderam ser retornados, devido a um número máximo predeterminado de itens que podem ser retornados em uma única resposta.
Uma origem que oferece suporte ao tipo de paginação de token de continuação pode ter um parâmetro de paginação semelhante a:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Propriedade | Descrição |
type |
O tipo de paginação usado para retornar dados. |
continuationTokenPath |
O valor que deve ser anexado aos parâmetros de consulta para passar para a próxima página dos resultados retornados. |
parameterType |
A propriedade parameterType define onde parameterName deve ser adicionado. O tipo QUERYPARAM permite anexar sua consulta com o parameterName . O HEADERPARAM permite que você adicione o parameterName à sua solicitação de cabeçalho. |
parameterName |
O nome do parâmetro usado para incorporar o token de continuação. O formato é: {PARAMETER_NAME}={CONTINUATION_TOKEN} . |
delayRequestMillis |
A propriedade delayRequestMillis na paginação permite controlar a taxa de solicitações feitas na origem. Algumas origens podem ter um limite para o número de solicitações que podem ser feitas por minuto. Por exemplo, Zendesk tem um limite de 100 solicitações por minuto e definir delayRequestMillis como 850 permite que você configure a fonte para fazer chamadas a apenas 80 solicitações por minuto, bem abaixo do limite de 100 solicitações por minuto. |
Este é um exemplo de uma resposta retornada usando o tipo de token de continuação de paginação:
code language-json |
---|
|
O tipo de paginação PAGE
permite percorrer os dados de retorno pelo número de páginas começando de zero. Ao usar a paginação do tipo PAGE
, você deve fornecer o número de registros fornecidos em uma única 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 | |
---|---|
Propriedade | Descrição |
type |
O tipo de paginação usado para retornar dados. |
limitName |
O nome do limite pelo qual a API pode especificar o número de registros a serem buscados em uma página. |
limitValue |
O número de registros a serem buscados em uma página. |
initialPageIndex |
(Opcional) O índice da página inicial define o número da página a partir da qual a paginação iniciará. Esse campo pode ser usado para fontes nas quais a paginação não começa em 0. Se não for fornecido, o índice da página inicial será padrão de 0. Este campo espera um número inteiro. |
endPageIndex |
(Opcional) O índice da página final permite estabelecer uma condição final e parar a paginação. Esse campo pode ser usado quando as condições finais padrão para interromper a paginação não estiverem disponíveis. Este campo também pode ser usado se o número de páginas que serão assimiladas ou o número da última página for fornecido por meio do cabeçalho de resposta, o que é comum ao usar a paginação do tipo PAGE . O valor do índice da página final pode ser o número da última página ou um valor de expressão do tipo string do cabeçalho de resposta. Por exemplo, você pode usar headers.x-pagecount para atribuir um índice de página final ao valor x-pagecount dos cabeçalhos de resposta. Observação: x-pagecount é um cabeçalho de resposta obrigatório para algumas fontes e contém o número de valor de páginas a serem assimiladas. |
pageParamName |
O nome do parâmetro que você deve anexar aos parâmetros de consulta para percorrer diferentes páginas dos dados de retorno. Por exemplo, https://abc.com?pageIndex=1 retornaria a segunda página de uma carga de retorno de API. |
maximumRequest |
O número máximo de solicitações que uma origem pode fazer para uma determinada execução incremental. O limite padrão atual é 10000. |
O tipo de paginação NONE
pode ser usado para fontes que não oferecem suporte a nenhum dos tipos de paginação disponíveis. As fontes que usam o tipo de paginação de NONE
simplesmente retornam todos os registros recuperáveis quando uma solicitação GET é feita.
code language-json |
---|
|
Programação avançada para Fontes de autoatendimento (SDK em lote)
Configure a programação incremental e de preenchimento retroativo da origem usando a programação avançada. A propriedade incremental
permite configurar um agendamento no qual sua origem assimilará somente registros novos ou modificados, enquanto a propriedade backfill
permite criar um agendamento para assimilar dados históricos.
Com a programação avançada, você pode usar expressões e funções específicas da origem para configurar programações incrementais e de preenchimento retroativo. No exemplo abaixo, a origem Zendesk requer que o agendamento incremental seja formatado como type:user updated > {START_TIME} updated < {END_TIME}
e o preenchimento retroativo 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 usar o tipo de agendamento avançado.scheduleParams.paramFormat
scheduleStartParamFormat
e scheduleEndParamFormat
da sua origem.scheduleParams.incremental
scheduleParams.backfill
Depois de configurar o agendamento avançado, consulte scheduleParams
na seção URL, corpo ou parâmetros de cabeçalho, dependendo do que a sua fonte específica suporta. No exemplo abaixo, {SCHEDULE_QUERY}
é um espaço reservado usado para especificar onde as expressões de agendamento de preenchimento retroativo e incremental serão usadas. No caso de uma origem Zendesk, query
é usado em queryParams
para especificar o agendamento avançado.
"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"
}
}
Adicione um esquema personalizado para definir os atributos dinâmicos de sua fonte
Você pode incluir um esquema personalizado em seu sourceSpec
para definir todos os atributos necessários para sua origem, inclusive os atributos dinâmicos que você possa precisar. Você pode atualizar a especificação de conexão correspondente de sua origem fazendo uma solicitação PUT para o ponto de extremidade /connectionSpecs
da API Flow Service e, ao mesmo tempo, fornecendo seu esquema personalizado na seção sourceSpec
da especificação de sua conexão.
Este é um exemplo de um esquema personalizado que você pode adicionar à especificação de conexão da origem:
"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"
}
}
}
}
}
}
}
Próximas etapas
Com suas especificações de origem preenchidas, você pode continuar a configurar as especificações de exploração para a origem que deseja integrar à Platform. Consulte o documento sobre configuração das especificações de exploração para obter mais informações.