開発者向け機能：API：テーブル操作：レコード作成・更新

2023/08/16

MANUAL

開発者向け機能：API：テーブル操作：レコード作成・更新

概要

APIを使用してレコードを作成または更新する事ができます。
指定したキー項目が一致するレコードがある場合はそのレコードを更新、一致するレコードがない場合は新規作成を行います。

制限事項

対象の「レコード」に「作成」および「更新」権限が必要です。

事前準備

APIの操作を行う前にAPIキーの作成を実施してください。

リクエスト

下記のリクエスト形式で、jsonデータを送信します。

設定項目	値
HTTPメソッド	POST
Content-Type	application/json
文字コード	UTF-8
URL	http://{サーバー名}/api/items/{サイトID}/upsert(※1)
Body	以下のjsonデータを参考のこと

(※1){サーバー名}、{サイトID}の部分は、適宜、環境に合わせて編集してください。
　　pleasanter.netの場合は以下の形式になります。
　　https://pleasanter.net/fs/api/items/{サイトID}/upsert

指定するキー項目について

指定したキー項目をもとにAPIによるレコード作成・更新(upsert)を行います。キー項目の指定は以下のパラメータで指定します。

プロパティ名	データ型	説明
Keys	配列(文字列)	キーとなる項目を指定。複数の項目を指定可能。

詳細につきましては、下記の (a)単一キーの場合、(b)複合キーの場合をご参照ください。

APIによる画像の挿入について

BodyにImageHashを指定することで内容、コメント、説明項目に画像を挿入することが可能です。更新系のAPI（update／upsert）で本機能によるレコード更新を行う場合、既存レコードの該当項目は内容、説明項目では上書き、コメント項目では追加となります。また、更新系のAPIで内容、説明項目に登録する文字列を指定するBodyやDescriptionHashを省略した状態でImageHashのみを指定すると、上書きではなく追加となります。

ImageHashの指定方法

第1階層	第2階層	第3階層	説明	例
ImageHash	Body	HeadNewLine	画像を挿入する際の先頭の改行有無をtrue/falseで指定します。省略した場合は改行無しになります。	true
		EndNewLine	画像を挿入する際の末尾の改行有無をtrue/falseで指定します。省略した場合は改行無しになります。	true
		Position	同じリクエスト内で対象項目に文字列を設定する場合に画像を何文字目に挿入するかを数値で指定します。-1を指定した場合および省略した場合は末尾に挿入されます。	3
		Alt	alt属性（Webブラウザで画像が表示できないときに、画像の代わりに表示されるテキスト）に挿入する文字列を指定します。省略した場合は「image」が設定されます。	hayato
		Extension	Binariesテーブルに登録するファイル拡張子を指定します。省略した場合は「.png」が設定されます。	.jpeg
		Base64	Base64エンコードした画像のバイナリデータを文字列で指定します。ImageHashを指定する場合、省略はできません。	iVBORw0KG…（以下略）
	Comments	（同上）	（同上）	-
	DescriptionA	（同上）	（同上）	-
	DescriptionB	（同上）	（同上）	-

APIによるプロセスの実行について

リクエストデータに、プロセスIDを指定し、プロセスを実行することが可能です。

事前準備

事前にプロセスを設定してください。

制限事項

APIからプロセスを実行する場合、プロセスで設定した入力検証は適用されません。

プロセスの指定方法

設定項目	説明	例
ProccessId	プロセスのIDを指定します。	1

(a)単一キーの場合

Keys パラメータにキーとなる項目の項目名を配列形式で設定します。Keys に指定した項目について、パラメータで指定した値と一致するレコードを検索します。

下記の例では、「ClassA」項目の値が "RC0001" のレコードを検索します。
レコードを検索した結果に応じて下記の処理が実行されます。

対象のレコードが存在しなかった場合: レコードが新規作成されます。
対象のレコードが１件存在した場合: そのレコードが更新されます。
対象のレコードが複数件存在した場合: レコードの作成・更新は行われず、エラーレスポンスが返却されます。

JSON

{
    "ApiVersion": 1.1,
    "ApiKey": "145Afa9AF2A10SafaA21641...",
    "Keys": [
        "ClassA"
    ],
    "Title": "新機能XXを開発する2",
    "Body": "ボディ2",
    "CompletionTime": "2018/3/31",
    "ProcessId": 1,
    "ClassHash": {
        "ClassA": "RC0001",
        "ClassB": "分類２",
        "ClassC": "その他2"
    },
    "NumHash": {
        "NumA": 100,
        "NumB": 200
    },
    "DateHash": {
        "DateA": "2019/01/01",
        "DateB": "2020/01/01"
    },
    "DescriptionHash": {
        "DescriptionA": "説明2",
        "DescriptionB": "概要2",
        "DescriptionC": "補足2"
    },
    "CheckHash": {
        "CheckA": false,
        "CheckB": true
    },
    "ImageHash": {
        "Body": {
            "HeadNewLine": true,
            "EndNewLine": true,
            "Position": 3,
            "Alt": "imageBody",
            "Extension": ".jpeg",
            "Base64": "iVBORw0KG..."
        },
        "DescriptionA": {
            "HeadNewLine": true,
            "EndNewLine": true,
            "Position": 3,
            "Alt": "imageDescriptionA",
            "Extension": ".jpeg",
            "Base64": "iVBORw0KG..."
        }
    }
}

(b)複合キーの場合

Keys パラメータに複数の項目名を設定した場合、Keys に指定したすべての項目について、パラメータで指定した値と一致するレコードを検索します。
下記の例では、「ClassA」項目の値が "RC0002" かつ、「ClassB」項目の値が "01" のレコードを検索します。

JSON

{
    "ApiVersion": 1.1,
    "ApiKey": "ad7816s5sD2safFafaD...",
    "Keys": [
        "ClassA",
        "ClassB"
    ],
    "Title": "新機能XXを開発する2",
    "Body": "ボディ2",
    "CompletionTime": "2018/3/31",
    "ClassHash": {
        "ClassA": "RC0002",
        "ClassB": "01",
        "ClassC": "その他2"
    },
    "NumHash": {
        "NumA": 100,
        "NumB": 200
    },
    "DateHash": {
        "DateA": "2019/01/01",
        "DateB": "2020/01/01"
    },
    "DescriptionHash": {
        "DescriptionA": "説明2",
        "DescriptionB": "概要2",
        "DescriptionC": "補足2"
    },
    "CheckHash": {
        "CheckA": false,
        "CheckB": true
    },
    "ImageHash": {
        "Body": {
            "HeadNewLine": true,
            "EndNewLine": true,
            "Position": 3,
            "Alt": "imageBody",
            "Extension": ".jpeg",
            "Base64": "iVBORw0KG..."
        },
        "DescriptionA": {
            "HeadNewLine": true,
            "EndNewLine": true,
            "Position": 3,
            "Alt": "imageDescriptionA",
            "Extension": ".jpeg",
            "Base64": "iVBORw0KG..."
        }
    }
}

レスポンス

下記の形式のjsonデータが返却されます。

JSON

レコードが新規作成された場合

{
    "Id": 12345,
    "StatusCode": 200,
    "LimitPerDate": 10000,
    "LimitRemaining": 9994,
    "Message": "\" 新機能XXを開発する2 \" を作成しました。"
}

レコードが更新された場合

{
    "Id": 12345,
    "StatusCode": 200,
    "LimitPerDate": 10000,
    "LimitRemaining": 9994,
    "Message": "\" 新機能XXを開発する2 \" を更新しました。"
}

作成または更新できなかった場合

{
    "Id": 12345,
    "StatusCode": 401,
    "Message": "認証できませんでした。"
}

エラー時の確認事項

・API使用時の注意点やエラーが発生する場合の確認事項
 ・FAQ:変更後の設定ファイルやAPIリクエスト(JSON形式)が正しく認識されない場合の確認事項

仕様変更について

※ 2019年10月よりAPIの仕様が一部変更となりました。

分類, 数値, 日付, 説明, チェック項目はjsonにそのまま記載する方法から「～Hash」の中に記載する方法へ変更されました。

※ 2018年11月よりAPIの仕様が一部変更となりました。

URLの形式が '/pleasanter/api_items/xxxx' から '/pleasanter/api/items/xxxx' に変更されました。
Content-Type の指定が'application/x-www-form-urlencoded' から 'application/json'に変更されました。