为自助源配置源规范(批处理SDK)

最近更新： 2025年4月4日
  • 主题：

创建对象：

  • 开发人员

Source规范包含特定于某个源的信息，包括与源的类别、测试版状态和目录图标相关的属性。 它们还包含有用的信息，如URL参数、内容、标题和计划。 Source规范还描述了从基本连接创建源连接所需的参数架构。 要创建源连接，必须使用架构。

有关完全填充的源规范示例，请参阅附录。

"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包含有关UI或API专属源的信息。
sourceSpec.attributes.uiAttributes显示特定于UI的源的信息。
sourceSpec.attributes.uiAttributes.isBeta一个布尔属性，指示源是否需要客户提供更多反馈才能添加到其功能中。
  • true
  • false
sourceSpec.attributes.uiAttributes.category定义源的类别。
  • advertising
  • crm
  • customer success
  • database
  • ecommerce
  • marketing automation
  • payments
  • protocols
sourceSpec.attributes.uiAttributes.icon定义用于在Experience Platform UI中呈现源的图标。mailchimp-icon.svg
sourceSpec.attributes.uiAttributes.description显示源的简要说明。
sourceSpec.attributes.uiAttributes.label显示用于在Experience Platform UI中呈现源的标签。
sourceSpec.attributes.spec.properties.urlParams包含有关URL资源路径、方法和支持的查询参数的信息。
sourceSpec.attributes.spec.properties.urlParams.properties.path定义从中获取数据的资源路径。/3.0/reports/${campaignId}/email-activity
sourceSpec.attributes.spec.properties.urlParams.properties.method定义请求资源获取数据时使用的HTTP方法。GET、POST
sourceSpec.attributes.spec.properties.urlParams.properties.queryParams定义支持的查询参数，这些参数可用于在发出获取数据的请求时附加源URL。 注意：任何用户提供的参数值都必须设置为占位符格式。 例如： ${USER_PARAMETER}。"queryParams" : {"key" : "value", "key1" : "value1"}将附加到源URL中： /?key=value&key1=value1
sourceSpec.attributes.spec.properties.spec.properties.headerParams定义在提取数据时需要在到源URL的HTTP请求中提供的标头。"headerParams" : {"Content-Type" : "application/json", "x-api-key" : "key"}
sourceSpec.attributes.spec.properties.bodyParams此属性可以配置为通过POST请求发送HTTP正文。
sourceSpec.attributes.spec.properties.contentPath定义包含需要摄取到Experience Platform的项列表的节点。 此属性应遵循有效的JSON路径语法，且必须指向特定数组。查看其他资源部分以了解内容路径中包含的资源示例。
sourceSpec.attributes.spec.properties.contentPath.path指向要引入到Experience Platform的收藏集记录的路径。$.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此属性允许您扁平化两个数组并将资源数据转换为Experience Platform资源。
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定义从用户的当前页面响应中或在创建下一页URL时必须提供的参数或字段，才能获取到下一页的链接。
sourceSpec.attributes.spec.properties.paginationParams.type显示源支持的分页类型的类型。
  • OFFSET：此分页类型允许您通过指定从何处开始结果数组的索引以及返回结果数的限制来解析结果。
  • POINTER：此分页类型允许您使用pointer变量指向需要随请求发送的特定项。 指针类型分页要求有效负载中的路径指向下一页。
  • CONTINUATION_TOKEN：此分页类型允许您将查询或标头参数附加到接续令牌，以从源中检索因预设最大值而未最初返回的剩余返回数据。
  • PAGE：此分页类型允许您将查询参数附加到分页参数，以按页遍历返回数据，从第0页开始。
  • NONE：此分页类型可用于不支持任何可用分页类型的源。 分页类型NONE在请求后返回整个响应数据。
sourceSpec.attributes.spec.properties.paginationParams.limitName限制的名称，API可通过该名称指定页面中要提取的记录数。limit或count
sourceSpec.attributes.spec.properties.paginationParams.limitValue页面中要获取的记录数。limit=10或count=10
sourceSpec.attributes.spec.properties.paginationParams.offSetName偏移属性名称。 如果分页类型设置为offset，则需要此项。offset
sourceSpec.attributes.spec.properties.paginationParams.pointerPath指针属性名称。 这需要指向指向下一页的属性的json路径。 如果分页类型设置为pointer，则需要此项。pointer
sourceSpec.attributes.spec.properties.scheduleParams包含定义源支持的计划格式的参数。 计划参数包括startTime和endTime，这两个参数允许您为批处理运行设置特定的时间间隔，从而确保不再获取在上一次批处理运行中获取的记录。
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的用户输入参数的示例，请参阅其他资源。

其他资源

以下部分提供了有关可对sourceSpec进行的其他配置的信息，包括高级计划和自定义架构。

内容路径示例

以下是MailChimp Members连接规范中contentPath属性的内容示例。

"contentPath": {
  "path": "$.members",
  "skipAttributes": [
    "_links",
    "total_items",
    "list_id"
  ],
  "overrideWrapperAttribute": "member"
}

spec.properties用户输入示例

以下是用户提供的spec.properties使用MailChimp Members连接规范的示例。

在此示例中，listId作为urlParams.path的一部分提供。 如果需要从客户检索listId，则还必须将其定义为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."
        }
      }
    }

Source规范示例

以下是使用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."
        }
      }
    }
  }