---
title: "転送元としてカスタムコネクタを作成する | TROCCO Docs"
slug: "create-source-custom-connector"
updated: 2026-08-03T23:52:18Z
published: 2026-08-03T23:52:18Z
canonical: "documents.trocco.io/create-source-custom-connector"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://documents.trocco.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 転送元としてカスタムコネクタを作成する

本ページでは、転送元としてカスタムコネクタを作成する手順について説明します。 接続情報や転送に関する設定については、以下のドキュメントを参照ください。

- [接続情報 - カスタムコネクタ](/docs/connection-configuration-custom-connector)
- [転送元 - カスタムコネクタ](/docs/data-source-custom-connector)

## 基本情報

| 項目名 | 必須 | 説明 |
| --- | --- | --- |
| 名前 | Yes | TROCCO内部で利用するカスタムコネクタの名前を入力します。 |
| メモ | No | TROCCO内部で利用するカスタムコネクタのメモを入力できます。 |

## コネクタ情報

| 項目名 | 必須 | 説明 |
| --- | --- | --- |
| ベースURL | Yes | カスタムコネクタで取得対象とするREST APIのベースURLを入力します。 ベースURLとは、APIのすべてのエンドポイントにアクセスする際の基本となるURLです。 例：`https://api.example.com/api/v1` |

## 認証情報

| 項目名 | 必須 | 説明 |
| --- | --- | --- |
| 認証種別 | Yes | 認証種別を選択します。**APIキー**または**OAuth2**による認証に対応しています。 選択した認証種別によって、認証情報で入力する項目が変わります。 |

### 認証種別でOAuth2を選択した場合の追加項目

| 項目名 | 必須 | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| グラントタイプ | Yes | `認可コード` | OAuthで認証を付与する方式（グラントタイプ）を選択します。 取得対象のAPIで利用できるグラントタイプを選択してください。 - 認可コード - クライアントクレデンシャルズ |
| 認可URL | Yes | - | グラントタイプに`認可コード`を選択した場合のみ、入力が必要な項目です。 OAuthの認可サーバーへの遷移先となる認可URLを入力します。利用するOAuthサービスから取得してください。 |
| アクセストークンURL | Yes | - | OAuthにアクセストークンをリクエストする先となるアクセストークンURLを入力します。利用するOAuthサービスから取得してください。 |

### 各認証種別で共通の項目

| 項目名 | 必須 | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| 認証ヘッダ名 | Yes | `Authorization` | APIキーを送信するヘッダーの名称を入力します。 |
| 認証スキーム | No | `Bearer` | 認証情報のスキームを入力します。 |

## エンドポイント

カスタムコネクタで取得対象とするAPIのエンドポイントごとに設定を追加します。

| 項目名 | 必須 | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| 名前 | Yes | - | エンドポイントの名前を入力します。 |
| パス | Yes | - | ベースURLで指定したURL部分を除いた、APIエンドポイントのパスを入力します。 |
| パスパラメータ | No | - | パスにパスパラメータを用いる際に入力します。 |
| HTTPメソッド | Yes | GET | HTTPメソッドを選択します。 `GET`と`POST`をサポートしています。 |
| パラメータ | No | - | リクエストに必要なパラメータを設定します。 - パラメータ名：実際に付与するパラメータの名称を設定します。 - 表示名：転送設定でパラメータを設定する際の表示名を入力します。 - デフォルト値：パラメータのデフォルト値を入力します。 - 編集可能：チェックを入れた場合、転送設定時にパラメータの値を入力できるようになります。 - 必須：チェックを入れた場合、転送設定時にパラメータの値の入力が必須になり、値が入力されていない場合はエラーになります。 |
| HTTPヘッダ | No | - | リクエストに必要なHTTPヘッダを設定します。 - デフォルト値：パラメータのデフォルト値を入力します。 - 編集可能：チェックを入れた場合、転送設定時にパラメータの値を入力できるようになります。 - 必須：チェックを入れた場合、転送設定時にパラメータの値の入力が必須になります。 |
| リクエストボディパラメータ | No | - | HTTPメソッドに`POST`を選択した場合に設定できます。リクエストボディに動的に埋め込む値をパラメータとして定義します。 定義したパラメータは`{パラメータ名}`の形式でリクエストボディ内に挿入でき、転送設定時にユーザーが値を指定できます。 - パラメータ名：リクエストボディ内で参照する変数名を設定します。 - 表示名：転送設定でパラメータを設定する際の表示名を入力します。 - デフォルト値：パラメータのデフォルト値を入力します。 - 編集可能：チェックを入れた場合、転送設定時にパラメータの値を入力できるようになります。 - 必須：チェックを入れた場合、転送設定時にパラメータの値の入力が必須になり、値が入力されていない場合はエラーになります。 利用方法について、詳しくは[リクエストボディパラメータの使い方](/docs/create-source-custom-connector#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%83%9C%E3%83%87%E3%82%A3%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9)を参照ください。 |
| リクエストボディ | No | - | HTTPメソッドに`POST`を選択した場合に入力できます。リクエストボディを設定します。 クエリパラメータ（パラメータ）を指定した場合、リクエストボディに設定した値はリクエストに含まれません。 リクエストボディパラメータを設定している場合は、**パラメータを挿入**ボタンを使ってリクエストボディ内に変数（`{パラメータ名}`形式）を挿入できます。 |
| JSONPathルート | Yes | `$.*` | レスポンスからデータを抽出する際のルートとするパスを[JSONPath記法](https://github.com/json-path/JsonPath#operators)で指定します。 |
| ページング設定 | Yes | 無効 | ページング設定を以下より選択します。 - **無効** - **ページベース** - **オフセットベース** - **カーソルベース** ページングリクエストを使用する場合は、リクエスト先の仕様に応じてページングを設定してください。 詳しくは、[ページング設定](/docs/create-source-custom-connector#%E3%83%9A%E3%83%BC%E3%82%B8%E3%83%B3%E3%82%B0%E8%A8%AD%E5%AE%9A)を参照ください。 |

              JSONPathルートの指定方法

              

- ページング設定の終了位置判定方法で「最終ページを自動判定」または「最終位置を自動判定」を利用する場合は、配列そのものを返すパスを指定してください。配列の要素を展開する式（`[*]`）を利用するとエラーになります。
  - 正しい例：`$.value`
  - エラーになる例：`$.value[*]`
- フィールド名に`.`（ドット）が含まれる場合は、ブラケット記法を使用してください。
  - 正しい例：`$['@odata.count']`
  - エラーになる例：`$.@odata.count`

### リクエストボディパラメータの使い方

リクエストボディパラメータを設定すると、リクエストボディ内に変数（`{パラメータ名}`）を挿入し、転送設定時にユーザーが値を上書きできるようになります。

たとえば、POSTメソッドのリクエストボディで検索条件を指定するAPIでは、「更新日時が指定日時以降のデータ」のように取得対象を絞り込むことが一般的です。 この絞り込み条件の値をリクエストボディに直接記述すると、取得対象の期間を変更するたびにカスタムコネクタの定義を編集する必要があります。 以下のように更新日時の値をリクエストボディパラメータ（例：`{updated_at_from}`）として定義しておくと、カスタムコネクタの定義を編集することなく、転送設定側で取得対象の期間だけを指定できます。

```
{
  "query": {
    "field": "updated_at",
    "operator": ">",
    "value": {updated_at_from}
  }
}
```

リクエストボディパラメータの値にはカスタム変数も埋め込めるため、スケジュール実行のたびに取得対象の期間をずらす差分転送のような運用も、転送設定側の設定だけで実現できます。

#### 1. カスタムコネクタでリクエストボディパラメータとリクエストボディを定義する

転送元カスタムコネクタの作成時に、リクエストボディパラメータとリクエストボディを定義します。

リクエストボディの入力エリアで**パラメータを挿入**ボタンをクリックすると、設定済みのリクエストボディパラメータ一覧が表示されます。 挿入したいパラメータの**カーソル位置に挿入**をクリックすると、リクエストボディ内のカーソル位置に`{パラメータ名}`が挿入されます。

#### 2. リクエストボディを確認する

**リクエストボディを参照**ボタンをクリックすると、現在のリクエストボディの内容を確認できます。 リクエストボディ内に挿入した`{パラメータ名}`形式の変数はハイライト表示されます。

#### 3. 転送設定でリクエストボディパラメータに値を設定する

転送設定の定義時に、カスタムコネクタで定義したリクエストボディパラメータに値を設定します。カスタム変数の埋め込みも可能です。 詳しくは、[転送元 - カスタムコネクタ](/docs/data-source-custom-connector)を参照ください。

              リクエストボディパラメータの削除

              

リクエストボディ内に`{パラメータ名}`として挿入済みのパラメータは削除できません。削除する場合は、先にリクエストボディ内の該当する変数を削除してください。

### 詳細設定

| 項目名 | 必須 | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| 転送データ取得時に正常系と判定するステータスコード | Yes | `200` | データ取得の成功とみなすレスポンスのステータスコードを指定します。 カンマ区切りで複数指定できます。 |
| 失敗時にリトライしないステータスコード | Yes | `400,401,403,404` | データ取得の失敗として再取得を実行しないレスポンスのステータスコードを指定します。 取得対象のデータが存在しない場合や、権限が足りない場合のステータスコードの指定を推奨します。 カンマ区切りで複数指定できます。 |
| リクエストタイムアウト(秒) | Yes | `30` | APIリクエストのタイムアウト時間を秒単位で指定します。 1〜1800の範囲で指定できます。 |

### 接続確認

設定したエンドポイントの接続を確認できます。

              
              

接続確認には事前に接続情報を設定する必要があるため、一度カスタムコネクタを作成して接続情報を設定したのち、実行してください。

              
              

現在ページング設定の接続確認でのサポートは行なっていません。

| 項目名 | 必須 | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| 接続確認に利用する接続情報 | Yes | - | 接続確認に利用する接続情報を選択します。 |
| パスパラメータ | No | - | エンドポイント設定で使用したパスパラメータの値を入力できます。 |
| 必須パラメータ | No | - | エンドポイント設定で「必須」としたパラメータの値を入力できます。 |
| 必須ヘッダー | No | - | エンドポイント設定で「必須」としたHTTPヘッダの値を入力できます。 |
| リクエストボディのテンプレート変数 | No | - | ページングパラメータの挿入先に**リクエストボディ（Liquidテンプレート）**を選択した場合に表示されます。リクエストボディに展開する値を入力できます。 空のままにした変数は、未設定として展開されます。 |

### ページング設定

#### ページングの方式

**ページング設定**で**ページベース**・**オフセットベース**・**カーソルベース**を選択すると、転送データ取得時にページングリクエストを含めることができます。 選択肢ごとに、設定項目は異なります。

**ページベースを選択した場合**

| 項目名 | デフォルト値 | 内容 |
| --- | --- | --- |
| 1リクエストの取得件数 | - | 1リクエストで取得するデータの件数を指定します。取得先のAPIによっては、上限が定められている場合があります。 |
| 開始ページ | - | ページングを開始するページ数を指定します。 |
| 終了ページ | 最終ページを自動判定 | 終了位置を判定する方法と、判定するための値を入力します。 - 最終ページを自動判定：取得件数が0件になったらページングを終了します。 - 総ページ数のパスを指定：総ページ数が格納されているレスポンスのパスを[JSONPath記法](https://github.com/json-path/JsonPath#operators)で指定し、総ページ数に到達したらページングを終了します。 - 終了ページを指定：ページングを終了するページ数を指定します。 |
| 最大リクエスト数 | 1000 | 終了位置で 最終ページを自動判定 を選択した場合にリクエストを行う最大回数を指定します。 |
| リクエストのプレビュー | - | リクエスト時に付与されるクエリパラメータを確認できます。 |

ページベースの入力例は以下の通りです。

| 項目名 | 値 |
| --- | --- |
| 1リクエストの取得件数 | - パラメータ名：`per_page` - 値：`100` |
| 開始ページ | - パラメータ名：`page` - 値：`1` |
| 終了ページ | - 終了判定方法：`終了ページを指定` - 値：`4` |

この場合、以下のようにパラメータが付与されたリクエストが実行されます。

1. `?per_page=100page=1`
2. `?per_page=100page=2`
3. `?per_page=100page=3`
4. `?per_page=100page=4`

**オフセットベースを選択した場合**

| 項目名 | デフォルト値 | 内容 |
| --- | --- | --- |
| 1リクエストの取得件数 | - | 1リクエストで取得するデータの件数を指定します。取得先のAPIによっては、上限が定められている場合があります。 |
| 開始位置 | - | ページングを開始するデータの位置を指定します。 |
| 終了位置 | 最終位置を自動判定 | 終了位置を判定する方法と、判定するための値を入力します。 - 最終位置を自動判定：取得件数が0件になったらページングを終了します。 - 総レコード数のパスを指定：総レコード数が格納されているレスポンスのパスを[JSONPath記法](https://github.com/json-path/JsonPath#operators)で指定し、総レコード数に到達したらページングを終了します。 - 終了位置を指定：ページングを終了するデータの位置を指定します。 |
| 最大リクエスト数 | 1000 | 終了位置で 最終位置を自動判定 を選択した場合にリクエストを行う最大回数を指定します。 |
| リクエストのプレビュー | - | リクエスト時に付与されるクエリパラメータを確認できます。 |

オフセットベースの入力例は以下の通りです。

| 項目名 | 値 |
| --- | --- |
| 1リクエストの取得件数 | - パラメータ名：`limit` - 値：`100` |
| 開始ページ | - パラメータ名：`offset` - 値：`0` |
| 終了位置 | - 終了判定方法：`終了位置を指定` - 値：`399` |

この場合、以下のリクエストパラメータが追加されます。

1. `?limit=100&offset=0`
2. `?limit=100&offset=100`
3. `?limit=100&offset=200`
4. `?limit=100&offset=300`

**カーソルベースを選択した場合**

              ページングリクエストの完了条件

              

カーソルベースのページング設定にした場合、レスポンスデータのカーソルが以下となるのが、リクエストの完了条件です。

- カーソルが含まれていない
- カーソルの値が`null`

そのため、データを取得したいサービスのAPI仕様が以下のいずれかの場合にのみ、カーソルベースをご利用いただけます。

- 後続ページがこれ以上存在しない場合、レスポンスデータにカーソルが含まれない
- 後続ページがこれ以上存在しない場合、レスポンスデータのカーソルの値が`null`

万一、上記仕様を満たさない仕様のAPIを利用して作成した転送設定でジョブを実行した場合は、リクエストの完了条件を満たせずジョブが終了しない可能性があります。 ジョブが終了しなくなった場合は、該当ジョブを手動でキャンセルしてください。

| 項目名 | デフォルト値 | 内容 |
| --- | --- | --- |
| レスポンスデータに含まれるカーソルへのパス（JSONPath記法） | - | レスポンスデータからカーソルの値を取り出す際に使用します。 [JSONPath記法](https://github.com/json-path/JsonPath#operators)で入力します。 |
| 取得位置 | - | 前ページのレスポンスデータで受け取ったカーソルをセットするパラメータ名を入力します。 |
| 1リクエストの取得件数 | - | 1リクエストで取得するデータの件数を指定します。取得先のAPIによっては、上限が定められている場合があります。 |

カーソルベースのレスポンスデータの構造が、以下だった場合の入力例です。

```
{
  "items": [
    { ... },
    { ... },
    ...
  ],
  "responseMetaData": {
    "nextCursor": "SAMPLE_CURSOR",
    ...
  },
  ...
}
```

| 項目名 | 値 |
| --- | --- |
| レスポンスデータに含まれるカーソルへのパス（JSONPath記法） | `$.responseMetaData.nextCursor` |
| 取得位置 | `cursor` |
| 1リクエストの取得件数 | - パラメータ名：`limit` - 値：`100` |

この場合、`?cursor=SAMPLE_CURSOR&limit=100`のようなリクエストパラメータが追加されます。

例えば、レコードが550件存在するデータに対するリクエストであれば、上記のようなリクエストが6回実行されます。 5回目までのレスポンスには100レコード分のデータが含まれ、6回目のレスポンスには50レコード分のデータが含まれます。 後続のデータが存在しない6回目のレスポンスデータにはカーソルが含まれないため、7回目のリクエストは実行せず、データ取得は完了します。

#### ページングパラメータの挿入先

ページングパラメータをリクエストのクエリパラメータ・リクエストボディのどちらに挿入するかを、**ページングパラメータの挿入先**で選択できます。 なお、リクエストボディ（Liquidテンプレート）はHTTPメソッドが`POST`の場合のみ選択できます。

**クエリパラメータを選択した場合パラメータを選択した場合**

ページングパラメータをクエリパラメータとして付与します。デフォルトの挿入先です。 POSTメソッドのリクエストボディにパラメータを指定するAPIでなければ、基本的にはこちらを選択します。

**リクエストボディ（Liquidテンプレート）を選択した場合**

ページングパラメータをクエリパラメータではなく、リクエストボディに挿入したい場合に選択します。 POSTメソッドで、ページング用のカーソルやページ番号をリクエストボディに含める仕様のAPIに対応できます。

リクエストボディは[Liquidテンプレート](https://shopify.github.io/liquid/)として扱われ、ページごとに展開されます。 ページングパラメータの名前を変数として、リクエストボディ内の任意の位置で参照できます。 このとき、ページングパラメータのパラメータ名を入力する項目は、**リクエストボディ内で参照するテンプレート変数名**に変わります。

              リクエストボディのプレビュー

              

ページング設定の**リクエストボディのプレビュー**で、初回リクエストと2ページ目以降の展開結果を、サンプル値で確認できます。 サンプル値を参考にしてリクエストボディを記載します。

              
              

以下の場合はパラメータをリクエストボディに挿入できません。

- 各ページングパラメータの変数名が、Liquidテンプレートの変数名として無効な形式
- 各ページングパラメータの変数名が重複している
- テンプレート展開後のリクエストボディが、不適切なJSON形式

              Liquidテンプレートとリクエストボディパラメータの違い

              

- ページング設定でリクエストボディ（Liquidテンプレート）を選択した場合のページングパラメータ：`{{ 変数名 }}`の形式
- リクエストボディパラメータ：`{パラメータ名}`（シングルブレース）の形式

カーソルベースを選択し、以下のように設定した場合の入力例です。

| 項目名 | 値 |
| --- | --- |
| レスポンスデータに含まれるカーソルへのパス（JSONPath記法） | `$.pages.next.starting_after` |
| 取得位置 | `starting_after` |
| 1リクエストの取得件数 | - テンプレート変数名：`per_page` - 値：`50` |

リクエストボディには、以下のようにページングパラメータの変数名を変数として記述します。

```
{
  "query": {
    "field": "updated_at",
    "operator": ">",
    "value": 1
  },
  "pagination": {
    "per_page": {{ per_page }}{% if starting_after %},
    "starting_after": "{{ starting_after }}"{% endif %}
  }
}
```

初回リクエストではカーソルがまだ存在しないため、取得位置の変数は展開されません。 `{% if %}`を用いることで、変数が設定されている場合のみ出力されるようにしています。 この場合、初回リクエストと2ページ目以降のリクエストでは、送信されるリクエストボディが以下のように異なります。

初回リクエストでは、以下のリクエストボディが送信されます。

```
{
  "query": {
    "field": "updated_at",
    "operator": ">",
    "value": 1
  },
  "pagination": {
    "per_page": 50
  }
}
```

2ページ目以降では、以下のリクエストボディが送信されます。

```
{
  "query": {
    "field": "updated_at",
    "operator": ">",
    "value": 1
  },
  "pagination": {
    "per_page": 50,
    "starting_after": "SAMPLE_CURSOR"
  }
}
```