json-no-code-connector

Domo JSON Connector — Product API リファレンス

REST/JSON API の主要なデータ取り込み経路です。 ソースが REST API の場合は、必ず最初に JSON コネクターを試してください。失敗した場合（認証、解析、ページネーションの問題）は、Java CLI（domo-data-upload スキル）に切り替えてください。2 経路のフォールバックパターンについては、そのスキルのガイドを参照してください。

概要

Domo JSON（No Code）コネクターでは、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 コネクターの作成には、次の 4 つの手順を順番に実行する必要があります。

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：トップレベルがフラットな配列 — 解析は不要

レスポンスがオブジェクトのフラットな配列であれば、解析ルールは必要ありません。配列の各要素が 1 行になり、各キーが 1 列になります。

[
  { "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 を使用して配列の各要素を 1 行にします。

{
  "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 が親のメタデータとともに 1 行になりました。

パターン 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 — 1 階層内側（例：ルートオブジェクト内のフィールド）
• 0.1.0 — 2 階層内側（例：expandRow の後、展開された各要素内）

処理後のフィールド名のルール：

• expandRow(data) の後、子フィールドには接頭辞が付きます：data.fact → data_fact
• flattenObject(name) の後、子フィールドには接頭辞が付きます：name.common → name_common
• 明示的にフラット化されていない、さらに深い階層のネストは、列内に JSON 文字列として残ります

認証タイプ

JSON コネクタは、コネクタが対象 API に対してどのように認証するかを制御する、複数の credentialsType 値をサポートしています。

認証なし

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"
    }
  }'

Basic 認証（ユーザー名／パスワード）

credentialsType: "fields" を使用し、設定に 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" を使用し、設定に 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
}

コネクタの作成（ストリーム）

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 } のメタデータオブジェクトの配列（下記を参照）

Configuration 配列

各エントリは、文字列化された JSON の value を持つ METADATA オブジェクトです。主なキーは次のとおりです。

name	用途
jsonSelection	URL、HTTP メソッド、ヘッダー、クエリパラメーター、日付フィルター、接続方法
jsonPaging	ページネーション設定：タイプ（offset/token など）、上限、ベース 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": ""
    }
  ]
}'

ストリームのレスポンスに関する注意事項

• レスポンスには、利用可能なすべての認証情報フィールドを示す authenticationSchemeConfiguration を含む、完全な dataProvider が含まれます。
• レスポンスの dataSource.id は、新しいデータセットの UUID です。
• アカウントが認証情報を使用して作成されている場合、account.valid は true になります。
• デフォルトのスケジュールは MANUAL です。自動実行するには、advancedScheduleJson を設定します（例：{"type":"DAY","at":"06:00 AM","timezone":"America/Denver"}）。

ストリームの実行

ストリームを作成した後、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 するだけです。
• ストリームを作成した後は、データがすぐに取り込まれるよう、必ず実行を開始してください。

HubSpot CRM パターン

HubSpot の CRM API（/crm/v3/objects/{type}）では、レコードが results 配列に格納され、各レコードにはネストされた properties オブジェクトがあります。Pattern 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" を使用し、Bearer トークンを jsonSelection.httpsHeaders に設定します。

"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 である必要があります。