json-no-code-connector

Domo JSON 连接器 — Product API 参考

REST/JSON API 的主要数据接入路径。 当数据源是 REST API 时，始终先尝试 JSON 连接器。如果失败（认证、解析或分页问题），回退到 Java CLI（domo-data-upload 技能）。关于双路径回退模式，请参阅该技能的指南。

概述

Domo JSON（无代码）连接器使用 dataProviderType: "json5"。它通过 Product API 进行管理：

POST /api/data/v1/accounts          Create an account
GET  /api/data/v1/accounts           List all accounts
GET  /api/data/v1/accounts/{id}      Get a specific account
POST /api/data/v1/streams                      Create a connector (stream)
GET  /api/data/v1/streams                      List all streams
GET  /api/data/v1/streams?limit=500            List streams (paginated)
POST /api/data/v1/streams/{id}/executions      Run a stream

对 API 本身的认证使用 X-Domo-Developer-Token 请求头。

工作流

创建 JSON 连接器需要按顺序完成四个步骤：

1. 检查 API — 获取目标 URL 并检查 JSON 结构，以确定正确的解析规则。
2. 创建账户（POST /api/data/v1/accounts）— 定义目标 API 的认证方式（无认证、基本认证或 API 密钥）。
3. 创建流（POST /api/data/v1/streams）— 定义连接器配置（URL、分页、解析）并将其与第 2 步创建的账户关联。
4. 运行流（POST /api/data/v1/streams/{id}/executions）— 触发连接器获取数据并填充数据集。

你必须先创建账户再创建流，因为流需要一个 accountId 引用。

第 1 步：检查 API 并规划解析

在创建连接器之前，获取 API URL 并检查 JSON 响应，以确定正确的 jsonParsing 规则。目标是将嵌套 JSON 扁平化为表格结构（行和列）。

curl -s "https://api.example.com/v1/data" | python3 -m json.tool | head -50

识别响应形态并选择正确的模式：

模式 A：顶层扁平数组 — 无需解析

如果响应已经是扁平的 JSON 对象数组，则不需要解析规则。每个数组元素成为一行，每个键成为一列。

[
  { "id": 1, "title": "...", "body": "...", "userId": 1 },
  { "id": 2, "title": "...", "body": "...", "userId": 1 }
]

解析：{"parsing": ""}

结果列：id、title、body、userId

已测试： JSONPlaceholder（/posts）→ 100 行，4 列。Jokes API（/jokes/ten）→ 10 行，4 列（type、setup、punchline、id）。

模式 B：对象包裹数组 — 使用 expandRow

如果响应是一个包含嵌套记录数组的对象，使用 expandRow 将每个数组元素转换为一行。

{
  "current_page": 1,
  "total": 332,
  "data": [
    { "fact": "Cats sleep 70% of their lives.", "length": 30 },
    { "fact": "A group of cats is called a clowder.", "length": 38 }
  ]
}

解析：{"parsing": "0.1:expandRow(data)\n"}

结果列：data_fact、data_length，以及所有顶层字段（current_page、total、per_page 等）在每一行上重复出现。

重要： 在 expandRow 之后，嵌套字段会以数组名作为前缀。因此 data[].fact 会变成 data_fact。

已测试： Cat Facts（catfact.ninja/facts）→ 100 行。data 数组被展开，每个 fact 成为一行，并重复父级元数据。

模式 C：带嵌套对象的顶层数组 — 使用 flattenObject

如果响应是顶层数组，但每个元素包含嵌套对象，使用 flattenObject 将嵌套键提升为顶层列。

[
  {
    "name": { "common": "France", "official": "French Republic" },
    "capital": ["Paris"],
    "region": "Europe",
    "population": 67390000
  }
]

解析：{"parsing": "0.0:flattenObject(name)\n"}

结果列：name_common、name_official、capital、region、population。nativeName 子对象（更深的嵌套）保持为 JSON 字符串，除非进一步扁平化。

深度表示法： 对于顶层数组，使用 0.0（数组中的第一个对象）。对于 expandRow 之后的嵌套数组，深度会增加（例如 0.1.0）。

已测试： REST Countries → 250 行。flattenObject(name) 生成了 name_common 和 name_official 作为单独的列。更深的 nativeName 保持为 JSON 字符串。

模式 D：单个对象包含嵌套对象 —— 使用多个 flattenObject

如果响应是单个对象（1 行）且包含嵌套对象，则分别展平每个嵌套对象。

{
  "latitude": 40.76,
  "longitude": -111.89,
  "current_weather": {
    "temperature": 11.6,
    "windspeed": 2.2,
    "winddirection": 270
  },
  "current_weather_units": {
    "temperature": "°C",
    "windspeed": "km/h"
  }
}

解析：{"parsing": "0.0:flattenObject(current_weather)\n0.0:flattenObject(current_weather_units)\n"}

结果列：latitude、longitude、current_weather_temperature、current_weather_windspeed、current_weather_winddirection、current_weather_units_temperature、current_weather_units_windspeed 等。

多个 flattenObject 规则可以共享相同的深度（0.0），前提是它们作用于同一层级的兄弟对象。

已测试： Open-Meteo Weather API → 1 行，21 列。current_weather 和 current_weather_units 均被展平，并带有前缀的列名。

模式 E：对象包含数组 + 嵌套对象 —— 组合 expandRow + flattenObject

对于像 GeoJSON 这样的复杂响应，需要链式操作。expandRow 先运行，然后 flattenObject 对展开后的结果进行操作。

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "event": "Flood Warning", "severity": "Moderate" },
      "geometry": { ... }
    }
  ]
}

解析：

0.1:expandRow(features)
0.1.0:flattenObject(features_properties)

关键细节： 在执行 expandRow(features) 之后，嵌套字段 properties 被引用为 features_properties（以数组名称作为前缀）。

已测试： NWS Weather Alerts API → 将 features 数组展开为行，然后将 properties 展平为单独的列。

解析规则参考

操作	语法	使用场景
expandRow(field)	depth:expandRow(arrayField)	对象包含一个应成为行的数组
flattenObject(field)	depth:flattenObject(objectField)	记录包含一个嵌套对象，其键应成为列

深度表示法：

• 0.0 —— 顶层（数组的第一个元素，或根对象）
• 0.1 —— 深入一层（例如根对象内的某个字段）
• 0.1.0 —— 深入两层（例如在执行 expandRow 之后，位于每个展开的元素内）

操作后字段名的规则：

• 在执行 expandRow(data) 之后，子字段会被添加前缀：data.fact → data_fact
• 在执行 flattenObject(name) 之后，子字段会被添加前缀：name.common → name_common
• 未显式展平的更深层嵌套会以 JSON 字符串的形式保留在列中

身份验证类型

JSON 连接器支持多个 credentialsType 值，用于控制连接器如何向目标 API 进行身份验证。

无身份验证

使用 credentialsType: "fields" 并将 authentication 设置为 "none"。适用于不需要凭据的公共 API。

curl -X POST "https://{instance}.domo.com/api/data/v1/accounts" \
  -H "X-Domo-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Public API Account",
    "displayName": "My Public API Account",
    "type": "data",
    "allowExternalUse": true,
    "dataProviderType": "json5",
    "credentialsType": "fields",
    "configurations": {
      "authentication": "none"
    }
  }'

基本身份验证（用户名/密码）

使用 credentialsType: "fields"，并在 configurations 中提供 username 和 password。

curl -X POST "https://{instance}.domo.com/api/data/v1/accounts" \
  -H "X-Domo-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Basic Auth Account",
    "displayName": "My Basic Auth Account",
    "type": "data",
    "allowExternalUse": true,
    "dataProviderType": "json5",
    "credentialsType": "fields",
    "configurations": {
      "username": "[email protected]",
      "password": "yourPassword"
    }
  }'

请求头中的 API 密钥

使用 credentialsType: "apikey_header"，并在 configurations 中提供 apiKey。

curl -X POST "https://{instance}.domo.com/api/data/v1/accounts" \
  -H "X-Domo-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key Account",
    "displayName": "My API Key Account",
    "type": "data",
    "allowExternalUse": true,
    "dataProviderType": "json5",
    "credentialsType": "apikey_header",
    "configurations": {
      "apiKey": "your-api-key-here"
    }
  }'

响应

API 返回所创建的账户对象。注意：

• configurations 将返回为 {}（空）—— 出于安全考虑，凭据不会被回显。
• valid 在响应中可能显示为 false，但该账户在前端是可用的。
• createdAt / modifiedAt 在初始响应中可能为 null。

响应示例

{
  "id": 117,
  "userId": 149955692,
  "name": "My API Key Account",
  "displayName": "My API Key Account",
  "type": "data",
  "valid": false,
  "allowExternalUse": true,
  "dataProviderType": "json5",
  "credentialsType": "apikey_header",
  "createdAt": null,
  "createdBy": 149955692,
  "modifiedAt": null,
  "modifiedBy": 149955692,
  "secretManagerAccountId": null,
  "secretId": null,
  "configurations": {},
  "accountId": 117,
  "accountTemplateId": null,
  "accountTemplateAuthorizationId": null
}

创建连接器（Stream）

使用 POST /api/data/v1/streams 创建一个完全配置的 JSON 连接器，并关联一个账户。

必填字段

字段	描述
transport	必须包含 type: "CONNECTOR"、description: "com.domo.connector.json.customparsing"、version: "4"
updateMethod	"REPLACE" 或 "APPEND"
dataProvider	{ "key": "json5" }
account	{ "id": <accountId>, "accountId": <accountId> } —— 引用之前创建的账户
dataSource	{ "name": "...", "description": "..." } —— 创建数据集
configuration	{ category, name, type, value } 元数据对象的数组（见下文）

配置数组

每个条目都是一个 METADATA 对象，带有字符串化的 JSON value。关键条目：

name	用途
jsonSelection	URL、HTTP 方法、请求头、查询参数、日期过滤、连接方式
jsonPaging	分页配置：类型（offset/token 等）、limit、base URL
jsonParsing	解析规则（例如 flattenObject(owner)）
schema	用于自动检测的 {"automatedSchema": true}
cloud	云标识符（例如 "domo"）
_description_	数据集描述（可以是空字符串）

完整示例

curl -X POST "https://{instance}.domo.com/api/data/v1/streams" \
  -H "X-Domo-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
  "transport": {
    "type": "CONNECTOR",
    "description": "com.domo.connector.json.customparsing",
    "version": "4"
  },
  "updateMethod": "REPLACE",
  "dataProvider": {
    "key": "json5"
  },
  "account": {
    "id": 116,
    "accountId": 116
  },
  "dataSource": {
    "name": "My JSON Connector",
    "description": "Created via API"
  },
  "configuration": [
    {
      "category": "METADATA",
      "name": "jsonSelection",
      "type": "string",
      "value": "{\"connectionMethod\":\"Advanced\",\"jsonUrl\":\"https://api.example.com/v1/data\",\"httpMethod\":\"GET\",\"jsonLineReader\":\"false\",\"escapeBackslash\":\"false\",\"httpsHeaders\":[],\"body\":\"\",\"queryParameters\":[],\"dynamicSetup\":[{}],\"useDateFilter\":false,\"dateSelection\":{\"dateType\":\"date_range\",\"startDate\":{\"type\":\"relative\",\"offset\":0},\"endDate\":{\"type\":\"relative\",\"offset\":0}},\"dateQueryParamsFormat\":\"yyyy-MM-dd\",\"certificateInputType\":\"NoCertificate\",\"encodeParameterKey\":true,\"encodeParameterValue\":true,\"datasetType\":\"static\",\"dateParameter\":{\"dateType\":\"single_date\",\"dateFrom\":\"relative\",\"dateFromOffset\":1,\"dateTo\":\"relative\",\"dateToOffset\":0,\"date\":\"relative\",\"dateOffset\":1},\"useBody\":false,\"dynamicValuesType\":\"enter\",\"rateLimitSelection\":\"false\",\"timeUnit\":\"second\",\"dateParameterType\":\"separate\",\"useDateAtMidnight\":false}"
    },
    {
      "category": "METADATA",
      "name": "jsonPaging",
      "type": "string",
      "value": "{\"baseUrl\":\"https://api.example.com/v1/data\",\"tokenType\":\"path\",\"pagingType\":\"offset\",\"parsing\":\"\",\"total\":\"false\",\"pageLimitValue\":\"50\",\"startPage\":\"1\",\"encodeParameterValue\":true,\"encodeParameterKey\":true,\"offsetParameter\":\"offset\",\"pageLimitParameter\":\"limit\"}"
    },
    {
      "category": "METADATA",
      "name": "jsonParsing",
      "type": "string",
      "value": "{\"parsing\":\"\"}"
    },
    {
      "category": "METADATA",
      "name": "schema",
      "type": "string",
      "value": "{\"automatedSchema\":true}"
    },
    {
      "category": "METADATA",
      "name": "cloud",
      "type": "string",
      "value": "domo"
    },
    {
      "category": "METADATA",
      "name": "_description_",
      "type": "string",
      "value": ""
    }
  ]
}'

Stream 响应说明

• 响应包含完整的 dataProvider，其中 authenticationSchemeConfiguration 显示所有可用的凭据字段。
• 响应中的 dataSource.id 是新数据集的 UUID。
• 如果账户是使用凭据创建的，account.valid 将显示 true。
• 默认计划为 MANUAL。为自动化运行设置 advancedScheduleJson（例如 {"type":"DAY","at":"06:00 AM","timezone":"America/Denver"}）。

运行 Stream（执行）

创建 stream 后，使用 POST /api/data/v1/streams/{streamId}/executions 触发其运行。

curl -X POST "https://{instance}.domo.com/api/data/v1/streams/{streamId}/executions" \
  -H "X-Domo-Developer-Token: {devToken}" \
  -H "Content-Type: application/json"

示例响应

{
  "streamId": 561,
  "executionId": 2,
  "startedAt": 1774666802.49,
  "endedAt": null,
  "updateMethod": "REPLACE",
  "currentState": "ACTIVE",
  "rowsInserted": 0,
  "bytesInserted": 0,
  "startedBy": "149955692",
  "errors": []
}

执行说明

• 运行时 currentState 为 "ACTIVE"，完成后为 "SUCCESS" 或 "ERROR"。
• 无需请求体 — 只需 POST 到该端点。
• 创建 stream 后，始终触发一次执行，以便立即填充数据。

HubSpot CRM 模式

HubSpot 的 CRM API（/crm/v3/objects/{type}）将记录包装在 results 数组中，并且每条记录都有一个嵌套的 properties 对象。使用模式 E（expandRow + flattenObject）：

响应结构：

{
  "results": [
    { "id": "123", "properties": { "email": "...", "firstname": "..." } }
  ],
  "paging": { "next": { "after": "124" } }
}

解析规则：

0.1:expandRow(results)
0.1.0:flattenObject(results_properties)

认证： 对账户使用 credentialsType: "fields" / authentication: "none"，并在 jsonSelection.httpsHeaders 中注入 Bearer token：

"httpsHeaders": [{"name": "Authorization", "value": "Bearer pat-na2-..."}]

结果列： results_id、results_properties_email、results_properties_firstname 等。

重要说明

• /api/data/v1/accounts/{id} 不支持 PUT 和 PATCH 方法 — 会返回 405。要更改凭据，请创建一个新账户。
• authType 字段不是 json5 的有效配置 — 使用它会返回 400 错误："Data provider 'json5' does not have 'authType' authentication scheme configuration"。
• 始终为数据连接器账户设置 type: "data"。
• configuration 数组的值必须是字符串化的 JSON — 而不是嵌套对象。