Configurar especificação de origem para Origens de Autoatendimento (SDK em Lote)

Última atualização: 4 de abril de 2025
  • Tópicos:

Criado para:

  • Desenvolvedor

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"
      ]
    }
  },
}
PropriedadeDescriçãoExemplo
sourceSpec.attributesContém informações sobre a fonte específica da interface do usuário ou da API.
sourceSpec.attributes.uiAttributesExibe informações sobre a origem específica da interface do usuário.
sourceSpec.attributes.uiAttributes.isBetaUm atributo booleano que indica se a fonte requer mais feedback dos clientes para ser adicionada à funcionalidade.
  • true
  • false
sourceSpec.attributes.uiAttributes.categoryDefine a categoria da origem.
  • advertising
  • crm
  • customer success
  • database
  • ecommerce
  • marketing automation
  • payments
  • protocols
sourceSpec.attributes.uiAttributes.iconDefine o ícone usado para a renderização da origem na interface do usuário do Experience Platform.mailchimp-icon.svg
sourceSpec.attributes.uiAttributes.descriptionExibe uma breve descrição da origem.
sourceSpec.attributes.uiAttributes.labelExibe o rótulo a ser usado para a renderização da origem na interface do Experience Platform.
sourceSpec.attributes.spec.properties.urlParamsContém informações sobre o caminho de recurso do URL, o método e os parâmetros de consulta compatíveis.
sourceSpec.attributes.spec.properties.urlParams.properties.pathDefine o caminho do recurso do qual buscar os dados./3.0/reports/${campaignId}/email-activity
sourceSpec.attributes.spec.properties.urlParams.properties.methodDefine o método HTTP a ser usado para fazer a solicitação ao recurso para buscar dados.GET, POST
sourceSpec.attributes.spec.properties.urlParams.properties.queryParamsDefine os parâmetros de consulta compatíveis que podem ser usados para anexar o URL de origem ao fazer uma solicitação para buscar dados. Observação: qualquer valor de parâmetro fornecido pelo usuário deve ser formatado como um espaço reservado. Por exemplo: ${USER_PARAMETER}."queryParams" : {"key" : "value", "key1" : "value1"} será anexado à URL de origem como: /?key=value&key1=value1
sourceSpec.attributes.spec.properties.spec.properties.headerParamsDefine cabeçalhos que precisam ser fornecidos na solicitação HTTP para o URL de origem ao buscar dados."headerParams" : {"Content-Type" : "application/json", "x-api-key" : "key"}
sourceSpec.attributes.spec.properties.bodyParamsEsse atributo pode ser configurado para enviar o corpo HTTP por meio de uma solicitação POST.
sourceSpec.attributes.spec.properties.contentPathDefine o nó que contém a lista de itens que devem ser assimilados na Experience Platform. Esse atributo deve seguir a sintaxe de caminho JSON válida e apontar para uma matriz específica.Exiba a seção de recursos adicionais para obter um exemplo do recurso contido em um caminho de conteúdo.
sourceSpec.attributes.spec.properties.contentPath.pathO caminho que aponta para os registros de coleção a serem assimilados na Experience Platform.$.emails
sourceSpec.attributes.spec.properties.contentPath.skipAttributesEssa propriedade permite identificar itens específicos do recurso identificado no caminho do conteúdo que devem ser excluídos de serem assimilados.[total_items]
sourceSpec.attributes.spec.properties.contentPath.keepAttributesEssa propriedade permite especificar explicitamente os atributos individuais que você deseja manter.[total_items]
sourceSpec.attributes.spec.properties.contentPath.overrideWrapperAttributeEsta propriedade permite que você substitua o valor do nome de atributo especificado em contentPath.email
sourceSpec.attributes.spec.properties.explodeEntityPathEssa propriedade permite nivelar duas matrizes e transformar dados de recursos em recursos do Experience Platform.
sourceSpec.attributes.spec.properties.explodeEntityPath.pathO caminho que aponta para os registros de coleção que você deseja nivelar.$.email.activity
sourceSpec.attributes.spec.properties.explodeEntityPath.skipAttributesEssa propriedade permite identificar itens específicos do recurso identificado no caminho da entidade que devem ser excluídos da assimilação.[total_items]
sourceSpec.attributes.spec.properties.explodeEntityPath.keepAttributesEssa propriedade permite especificar explicitamente os atributos individuais que você deseja manter.[total_items]
sourceSpec.attributes.spec.properties.explodeEntityPath.overrideWrapperAttributeEsta propriedade permite que você substitua o valor do nome de atributo especificado em explodeEntityPath.activity
sourceSpec.attributes.spec.properties.paginationParamsDefine os parâmetros ou campos que devem ser fornecidos para obter um link para a próxima página da resposta da página atual do usuário ou ao criar um URL da próxima página.
sourceSpec.attributes.spec.properties.paginationParams.typeExibe o tipo de paginação suportada para a sua origem.
  • 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á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.
  • 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ção NONE retorna todos os dados de resposta após uma solicitação.
sourceSpec.attributes.spec.properties.paginationParams.limitNameO nome do limite pelo qual a API pode especificar o número de registros a serem buscados em uma página.limit ou count
sourceSpec.attributes.spec.properties.paginationParams.limitValueO número de registros a serem buscados em uma página.limit=10 ou count=10
sourceSpec.attributes.spec.properties.paginationParams.offSetNameO nome do atributo offset. Isso é necessário se o tipo de paginação for definido como offset.offset
sourceSpec.attributes.spec.properties.paginationParams.pointerPathO nome do atributo de ponteiro. Isso requer o caminho json para o atributo que apontará para a próxima página. Isso é necessário se o tipo de paginação for definido como pointer.pointer
sourceSpec.attributes.spec.properties.scheduleParamsContém parâmetros que definem formatos de agendamento compatíveis com a sua origem. Os parâmetros de agendamento incluem 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.scheduleStartParamNameDefine o nome do parâmetro da hora inicialsince_last_changed
sourceSpec.attributes.spec.properties.scheduleParams.scheduleEndParamNameDefine o nome do parâmetro da hora finalbefore_last_changed
sourceSpec.attributes.spec.properties.scheduleParams.scheduleStartParamFormatDefine o formato com suporte para o scheduleStartParamName.yyyy-MM-ddTHH:mm:ssZ
sourceSpec.attributes.spec.properties.scheduleParams.scheduleEndParamFormatDefine o formato com suporte para o scheduleEndParamName.yyyy-MM-ddTHH:mm:ssZ
sourceSpec.spec.propertiesDefine os parâmetros fornecidos pelo usuário para buscar valores do recurso.Consulte os recursos adicionais para obter um exemplo de parâmetros inseridos pelo usuário para spec.properties.