メインコンテンツへスキップ

レコード一覧 API

Canbus. チーム
  • 更新

レコード一覧 API を使用すると、アプリから条件に一致するレコードのリストを取得できます。

  • エンドポイント URL - https://<tenant-id>.canbus.com/api/records
  • メソッド - GET

 

リクエストヘッダーの形式

以下のリクエストヘッダーが必要です。

  • Content-Type: application/json

 

リクエストボディの形式

レコード一覧 API のリクエストボディには、対象レコードを検索する方法に応じて 2 つの形式があります。

フィルター ID を指定して検索する場合

{
    "tenant_id": <tenant_id>,
    "app_id": <app-id>,
    "api_key": <api-key>,
    "api_secret": <api-secret>,
    "record_list": {
        "filter": <filter-id>,
        "start": <start-index>,
        "number": <count>
    }
}

淡色部分には、Canbus. API の認証情報を挿入します。認証情報の送信方法については、認証を参照してください。

record_list は単一のオブジェクトです。省略可能なプロパティ filter, start, number を指定可能です。

filter は、レコード一覧画面で選択可能なフィルターの ID です。指定したフィルターの設定に一致するレコードが取得されます。filter を省略すると、デフォルトで「すべてのレコード」という名前を持つ、テーブルのデフォルトフィルターの設定が使用されます。

 

デフォルトフィルター以外のフィルターを使用する場合、該当するフィルターの ID を文字列で指定します。Canbus. のウェブ画面上ではフィルターの ID を直接確認することができないため、以下のように取得してください。

  1. レコード一覧画面で、使用するフィルターを選択します。
  2. ブラウザの機能を使用して、表示中のウェブページのソースを表示します。
  3. ソースの末尾近くまでスクロールし、次のような行を見つけます。
        window.GLOBAL.FILTER_ID = '663854886a831e0f49227227';
  4. 引用符内の 24 文字の文字列を取得します。上の例では 663854886a831e0f49227227 です。これがフィルター ID です。

start と number は、レコード一覧 API でレコードを取得する開始位置と、取得する最大レコード数です。省略すると、start の値として 0, number の値として 20 が使用されます。この場合、フィルターの並び順で先頭から最大 20 件のレコードが取得されます。start の値は 0 ベースであるため、0 が 1 件目のレコードを表すことに注意してください。

number に指定可能な最大値は 1000 です。テーブル内に 1,000 件を超えるレコードが登録されている場合、すべてのレコードを取得するには、start の値を変更しながら繰り返しレコード一覧 API を呼び出す必要があります。

もっとも単純な呼び出しでは、record_list は次のようになります。

"record_list": {
}

この場合、テーブルの「すべてのレコード」フィルターを使用して、先頭から最大 20 件のレコードを取得できます。

デフォルトフィルター以外のフィルターを使用して、フィルターで指定された並び順の先頭から最大 100 件のレコードを取得する場合、record_list は次のようになります。

"record_list": {
    "filter": "663854886a831e0f49227227",
    "start": 0,
    "number": 100
}

 

フィルター条件、取得する項目、並び順を指定して検索する場合

{
　　　　"tenant_id": <tenant_id>,
    "app_id": <app-id>,
    "api_key": <api-key>,
    "api_secret": <api-secret>,
    "record_list": {
        "query": {
            "filter": {
                <filter-condition-form-item-id>: <value>,
                ...
            },
            "items": [
                <form-item-id>,
                ...
            ],
            "sort": [
                <form-item-id>,
                ...
            ]
        },
        "start": <start-index>,
        "number": <count>
    }
}

この形式のリクエストボディを使用すると、レコード一覧画面で事前に設定されたフィルター以外の条件でレコード一覧 API を呼び出すことができます。

淡色部分には、Canbus. API の認証情報を挿入します。認証情報の送信方法については、認証を参照してください。

record_list は単一のオブジェクトです。必須の query と、省略可能な start, number を指定可能です。

query は、取得するレコードのフィルター条件、取得する項目、並び順をプロパティとして含むオブジェクトです。

query.filter は、フィルター条件を表すオブジェクトです。プロパティとして、フォーム項目 ID と一致条件を 0 個以上指定します。フィルター条件は、完全一致で比較されます。大小比較、部分一致、日付範囲などの比較はサポートされていません。

もっとも単純な query.filter の形式は次のようになります。

"query": {
    "filter": {
    }
    ...
}

この場合、フィルター条件を指定せず、テーブルのすべてのレコードを取得します。テーブルの「すべてのレコード」に設定されているフィルター条件も適用されないことに注意してください。

フィルター条件を指定する場合は、次のように query.filter のプロパティを設定します。

"query": {
    "filter": {
        "Text": "GA",
        "Number": 2024,
        "System_Create_User": "admin"
    }
    ...
}

この場合、Text 項目の値が "GA" であり、Number 項目の値が 2024 であり、作成者が admin であるすべてのレコードを抽出して取得します。

以下のフォーム項目型は、query.filter の条件として使用できません。

  • ラベル
  • リッチテキスト
  • 添付ファイル
  • 表組み（表組み内の項目を含む）
  • アプリ連携
  • レコード参照
  • グリッド参照
  • 罫線
  • ボタン

 

query.items は、取得するフォーム項目を表す文字列配列です。取得するフォーム項目の ID を 0 個以上指定します。

空の配列を指定した場合、フォーム項目の値は取得せず、レコードの ID だけを取得します。

"items": []

フォーム項目の ID を指定すると、query.filter の条件に一致するレコードのうち、指定した項目の値だけが取得されます。

"items": [
    "Text",
    "Number",
    "DateTime",
    "System_Record_ID",
    "System_Update_User",
    "System_Update_Time"
]

上記の場合、レコード ID に加えて、項目 ID が Text, Number, DateTime である項目と、レコード番号、更新者、更新日時を取得します。

レコードのすべての項目を取得するための構文はサポートされていません。取得するすべてのフォーム項目の ID を query.items で列挙する必要があります。

 

query.sort は、レコードの並び順を表す文字列配列です。昇順にソートする場合はフォーム項目の ID を指定し、降順にソートする場合は項目 ID の前にチルダ (~) を指定します。

次の例では、更新日時の降順でレコード一覧を取得します。

"sort": [
    "~System_Update_Time"
]

次の例では、Text の昇順、Number の昇順、Date の降順でレコード一覧を取得します。

"sort": [
    "Text",
    "Number",
    "~Date"
]

query.sort に空の配列を指定した場合、ソートは行われず、取得されるレコードの並び順は不定になります。API を繰り返し呼び出した場合に、並び順が一貫したものになることも保証されません。このため、1 回のレコード取得 API 呼び出しでテーブル内のすべてのレコードを取得できることが分かっている場合を除き、query.sort を空の配列にすることは避けてください。

 

query の全体は次のようになります。

"query": {
    "filter": {
        "Text": "GA",
        "Number": 2024,
        "System_Create_User": "admin"
    },
    "items": [
        "Text",
        "Number",
        "DateTime",
        "System_Record_ID",
        "System_Update_User",
        "System_Update_Time"
    ],
    "sort": [
        "~System_Update_Time"
    ]
}

start と number は、レコード一覧 API でレコードを取得する開始位置と、取得する最大レコード数です。省略すると、start の値として 0, number の値として 20 が使用されます。この場合、query.sort の並び順で先頭から最大 20 件のレコードが取得されます。start の値は 0 ベースであるため、0 が 1 件目のレコードを表すことに注意してください。

number に指定可能な最大値は 1000 です。テーブル内に 1,000 件を超えるレコードが登録されている場合、すべてのレコードを取得するには、start の値を変更しながら繰り返しレコード一覧 API を呼び出す必要があります。

 

レスポンスボディの形式

レコード一覧 API のレスポンスボディ形式は次のとおりです。

{
    "authen": "OK",
    "results": [
        {
            "result": <result-code>,
            "count": <total-record-count>,
            "length": <retrieved-record-count>,
            "records": [
                {
                    "_id": <record-object-id>,
                    <form-item-id>: <form-item-value>,
                    ...
                },
                ...
            ]
        }
    ]
}

レコード取得 API では、results はただ 1 つの要素を持つオブジェクト配列です。先頭要素の result コードは以下のいずれかの値になります。

  • 0 - 取得に成功
  • 7030 - リクエストボディで filter と query が同時に指定された
  • 7031 - リクエストボディの query.filter で存在しないフォーム項目 ID が指定された
  • 7032 - リクエストボディの query.items で無効なフォーム項目 ID が指定された
  • 7033 - リクエストボディの query.filter で指定された項目と指定された値との間に不整合がある場合。例えば、文字列項目に対して数値が指定された場合
  • 7034 - その他のエラー

count は、指定されたフィルター条件に一致するレコードの総数です。length は、レコード総数のうち今回のレコード一覧 API 呼び出しで返されたレコード数を表し、records の要素数に一致します。

records は、取得されたレコードの内容を表すオブジェクト配列です。

配列 records の各要素の _id は、取得されたレコードの ID です。レコード一覧 API で取得したレコード ID を使用して、レコード取得 API, レコード編集 API, レコード削除 API を呼び出すことができます。

配列要素のその他のプロパティとして、取得されたレコードの各フォーム項目の ID がそのまま返されます。プロパティの値は、各フォーム項目に対してレコードで入力されている値です。

 

未入力項目の値

レコードに未入力項目がある場合、その項目を表すプロパティ自体が records 要素に含まれません。プロパティの値がブランク、空の文字列、null になるわけではないため、注意してください。

レコード一覧 API だけでは、特定のレコードの項目が未入力になっているだけなのか、それともその項目自体がフォーム上に存在しないのかを区別できません。テーブル上に存在するすべてのフォーム項目を確認するには、メタデータ API を使用してください。

 

項目値の形式

レコード一覧 API で返される各フォーム項目の値は、項目の型に応じて以下の形式になります。

  • 数値 - フォーム上で入力された数値
  • 文字列 - フォーム上で入力された文字列
  • リッチテキスト - リッチテキストの HTML 表現
  • 日付 - "YYYY/MM/DD" 形式の文字列
  • 時刻 - "HH:MM" 形式の文字列
  • 日付と時刻 - "YYYY/MM/DD HH:MM" 形式の文字列
  • 添付ファイル - すべての添付ファイル名をカンマ区切りで連結した文字列
  • ラジオボタン - 選択された選択肢のラベル
  • チェックボックス - 選択された選択肢のラベルをカンマ区切りで連結した文字列
  • プルダウン - 選択された選択肢のラベル
  • 計算式 - 計算結果を表す文字列、数値、または日付と時刻を表す文字列
  • ユーザー選択 - 選択されたユーザーの表示名。表示名が設定されていない場合はログイン ID
  • 表組み - 表組み内の各行を JSON 文字列として表した JSON 配列
  • 組織選択 - 選択された組織名を、最上位の組織から "/" 区切りで連結した文字列
  • レコード番号 - 数値
  • 作成者 - レコードの作成者であるユーザーのログイン ID
  • 作成日時 - "YYYY/MM/DD HH:MM" 形式の文字列
  • 更新者 - レコードの最終更新者であるユーザーのログイン ID
  • 更新日時 - "YYYY/MM/DD HH:MM" 形式の文字列
  • 作成者の組織 - レコードの作成者の所属組織名を、最上位の組織から "/" 区切りで連結した文字列
  • ステータス - ステータス名の文字列

ラベル、罫線、ボタン、レコード参照、グリッド参照の各項目はレコード一覧画面に配置できないため、レコード一覧 API のレスポンスには含まれません。

各レコードのレコード参照項目またはグリッド参照項目の内容を取得する場合は、レコード取得 API を使用してください。

 

ページング

レコード一覧 API のリクエストボディでは、number に指定可能な最大値は 1000 です。1,000 件を超えるレコードをテーブルから取得するには、複数回のレコード一覧 API 呼び出しが必要になります。

これには、start の値を変更しながら以下のように繰り返しレコード一覧 API を呼び出します。

"record_list": {
　　　　"start": 0,
    "number": 100
}

最初は、上記のように start に 0 を指定します。

ここでは number に 100 を指定しているため、最大 100 件のレコードが取得されます。レスポンスボディに含まれる results 先頭要素の length を確認して、実際に取得されたレコード数が 100 よりも小さければ、テーブルには 100 件未満のレコードしかなく、すべてのレコードが取得されたことを表しています。

length が 100（リクエスト時に指定した number の値）と等しい場合、テーブルにちょうど 100 件のレコードがあるか、またはそれ以上のレコードが残っていることを表しています。この場合、start の値を調整してもう一度レコード一覧 API を呼び出します。

"record_list": {
　　　　"start": 100,
    "number": 100
}

上記のように start に 100 を指定することで、前回取得されたレコードの続きから最大 100 件のレコードが取得されます。

3 回目のリクエストが必要な場合は、次のようになります。

"record_list": {
　　　　"start": 200,
    "number": 100
}

レスポンスボディの length がリクエストボディで指定した number よりも小さくなるまで同様にリクエストを繰り返すことで、テーブルのレコードをすべて取得することが可能です。

ページング処理と並行してテーブルに新しいレコードが追加されたり、既存のレコードが削除される可能性がある場合には、ページング処理で取得されるレコード全体にも漏れや重複が発生する可能性があることに注意してください。ある時点のテーブル全体のスナップショットを取得する方法は、現在の Canbus. API ではサポートされていません。

 

関連情報

関連記事