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

レコード編集 API

Canbus. チーム
  • 更新

レコード編集 API を使用すると、アプリ内の指定されたレコードを編集できます。

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

 

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

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

  • Content-Type: application/json

 

リクエストボディの形式

レコード編集 API のリクエストボディ形式は次のとおりです。

{
    "tenant_id": <tenant-id>,
    "app_id": <app-id>,
    "api_key": <api-key>,
    "api_secret": <api-secret>,
    "update": [
        {
            "_id": <record-object-id>,
            "System_Update_User": <user-login-id>,
            <form-item-id>: <form-item-value>,
            ...
        },
        ...
    ]
}

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

update はオブジェクト配列です。レコードの編集内容を表す 1 個以上のオブジェクトを要素として指定します。各要素に含まれる _id は編集するレコードの ID を、System_Update_User はレコードの更新者として記録するユーザーのログイン ID をそれぞれ表す文字列です。この 2 つの必須のプロパティに加えて、編集するフォーム項目の ID を表すプロパティ名と、編集後の項目値をフォーム項目の型に応じて指定します。

編集するレコードのレコード ID を確認するには、最初にレコード一覧 API を使用して対象レコードを取得してください。レコード作成 API を使用してレコードを作成した場合は、作成されたレコードの ID がレコード作成 API のレスポンスボディに格納されています。ID がレコード作成後に変更されることはありません。レコードの ID はレコード番号とは異なります。

実際の update 配列のサンプルをいくつか例示します。

"update": [
    {
        "_id": "660fa9bd6a831e0f4f02446f",
        "System_Update_User": "admin"
    }
]

この呼び出しでは、指定したレコードがユーザー admin によって更新されます。編集するフォーム項目の ID を指定していないため、レコード上のどの項目の値も変更されず、API 呼び出し前のままです。（ただし、レコードの最終更新日時は更新されます）

"update": [
    {
        "_id": "660fa9bd6a831e0f4f02446f",
        "System_Update_User": "admin",
        "Text": "これは文字列項目 Text の編集後の値です",
        "Number": 1812
    }
]

この呼び出しでは、指定されたレコードの Text 項目と Number 項目の値が編集されます。他の項目の値は、API 呼び出し前のまま変更されません。

レコードを 2 件同時に編集するには、次のようにします。

"update": [
    {
        "_id": "660fa9bd6a831e0f4f02446f",
        "System_Update_User": "admin",
        "Text": "これは文字列項目 Text の再編集後の値です",
        "Number": 1945
    }, {
        "_id": "660a68da55b09b0c1815bc30",
        "System_Update_User": "admin",
        "Number": 81363673871
    }
]

この呼び出しでは、最初のレコードの Text 項目、Number 項目が編集され、2 番目のレコードの Number 項目が編集されます。

 

項目値の形式

レコード編集 API で指定可能な各フォーム項目の値は、項目の型に応じて形式が異なります。レコード作成 API の説明を参照してください。

 

レスポンスボディの形式

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

{
　　　　"authen": "OK",
    "results": [
        {
            "result": <result-code>,
            "id": <record-object-id>,
        },
        ...
    ]
}

results は編集結果を表すオブジェクト配列です。リクエストボディの update 配列の要素数と results の要素数は同じになり、互いの各要素が 1 対 1 で対応します。

レコード編集 API では、編集しようとしたレコードごとに以下の result コードが返されます。

  • 0 - 編集に成功
  • 32 - System_Update_User またはユーザー選択項目に指定されたログイン ID のユーザーが存在しない、または有効ではない
  • 99 - 組織選択項目に指定された組織が存在しない
  • 7001 - 数値項目に指定された値が最小値の制限を満たしていない
  • 7002 - 数値項目に指定された値が最大値の制限を満たしていない
  • 7003 - 数値で値を指定する必要がある項目に文字列の値を指定した
  • 7004 - 数値で値を指定する必要がある項目に対して指定範囲外の値を指定した
  • 7012 - 重複禁止項目に重複する値を指定した
  • 7013 - 入力必須項目に値が指定されていない
  • 7014 - 文字列項目に指定された値が入力可能文字の制限を満たしていない
  • 7018 - 数値項目に指定された値がシステム上の上限値 (999,999,999,999,999) を超えた
  • 7020 - 日付と時刻項目に指定された値が正しい形式でない
  • 7021 - 日付項目に指定された値が正しい形式でない
  • 7022 - 時刻項目に指定された値が正しい形式でない
  • 7042 - その他のエラー。例えば、チェックボックスや表組み項目に指定された値が正しい配列形式になっていない

result コードが 0 以外の値になっている場合、レコードは編集されていません。

複数のレコードを一度に編集しようとした場合、編集に成功したレコードと、何らかのエラーによって編集に失敗したレコードが混在することがあります。results の要素ごとに、result コードを確認してください。

各要素の id は、リクエストボディの update 配列で指定されたレコード ID です。この値は、指定された ID のレコードが実際に編集されたかどうかに関わらず、レスポンスボディに含まれます。

 

レコード編集時の入力検証

レコード上の既存項目に対するエラーチェックにより、レコード編集 API の呼び出しが失敗する場合があります。

例えば、テーブルのフォーム編集画面で項目の設定を調整し、ある項目を入力必須に変更したとします。この場合、このテーブルの既存レコードの中には、入力必須項目に値が入っていないレコードが存在する可能性があります。このような既存レコードに対してレコード編集 API を呼び出した場合、レコードの保存前にすべての項目の入力チェックが行われた結果、result コード 7013 が返されることがあります。

これは、ウェブ画面上で既存レコードを開き、上書き保存しようとした場合の動作に似ています。レコードの保存前には、現在のテーブル設定に基づいてすべての項目の入力検証が行われます。たとえ入力必須項目の値を変更していなくても、入力必須項目に値が入力されていない場合には、レコードは保存エラーになります。レコード編集 API でも同様に、配列 update の要素オブジェクトのプロパティとして指定したかどうかに関わらず、すべての項目の入力検証が行われ、値が入力されていない入力必須項目がある場合には result コード 7013 が返されます。

 

関連情報

関連記事