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

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

• 接続情報 - カスタムコネクタ
• 転送元 - カスタムコネクタ

基本情報

コネクタ情報

認証情報

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

各認証種別で共通の項目

エンドポイント

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

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

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

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

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

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

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

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

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

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

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

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

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

詳細設定

接続確認

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

ページング設定

ページングの方式

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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