レコード作成・更新
概要¶
APIを使用して、レコードを作成・更新します。
- 指定したキー項目が一致するレコードがある場合:該当レコードを更新
- 指定したキー項目の値がNULLの場合:レコードを新規作成
- 一致するレコードがない場合:レコードを新規作成
制限事項¶
- 対象の「レコード」に「作成」および「更新」権限が必要です。
- Wikiでは使用できません。
事前準備¶
APIの操作を行う前にAPIキーの作成を実施してください。
リクエスト¶
下記のリクエスト形式で、JSONデータを送信します。
| 設定項目 | 値 |
|---|---|
| HTTPメソッド | POST |
| Content-Type | application/json |
| 文字コード | UTF-8 |
| URL | http://{サーバ名}/api/items/{サイトID}/upsert1 |
| Body | 以下のJSONデータを参考のこと。詳細は「JSONデータレイアウト:共通」を参照してください。 |
指定するキー項目について¶
指定したキー項目をもとにAPIによるレコード作成・更新(upsert)を行います。キー項目の指定は以下のパラメータで指定します。
| プロパティ名 | データ型 | 説明 |
|---|---|---|
| Keys | 配列(文字列) | キーとなる項目を指定。複数の項目を指定可能。 |
Keysに指定した項目の値がNULLの場合、キー項目としての比較はされず、レコードが新規作成されます。
詳細につきましては、下記の (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からプロセスを実行する場合、プロセスで設定した入力検証は適用されません。
プロセスの指定方法¶
ProcessId または ProcessIds のいずれか一方を設定してください。
両方が設定された場合は、ProcessIds が有効です。
ProcessIds を指定した場合、リストで指定された複数のプロセスIDは、事前に設定されているプロセス一覧の表示順に従って実行されます。
| 設定項目 | 説明 | 例 |
|---|---|---|
| ProcessId | プロセスのIDを指定します。 | 1 |
| ProcessIds | 複数のプロセスのIDを指定します。 | [1,2,3] |
(a)単一キーの場合¶
Keys パラメータにキーとなる項目の項目名を配列形式で設定します。Keys に指定した項目について、パラメータで指定した値と一致するレコードを検索します。
下記の例では、「ClassA」項目の値が "RC0001" のレコードを検索します。
レコードを検索した結果に応じて下記の処理が実行されます。
- 対象のレコードが存在しなかった場合: レコードが新規作成されます。
- 対象のレコードが1件存在した場合: そのレコードが更新されます。
- 対象のレコードが複数件存在した場合: レコードの作成・更新は行われず、エラーレスポンスが返却されます。
JSON¶
{
"ApiVersion": 1.1,
"ApiKey": "145Afa9AF2A10SafaA21641...",
"SsCache": true,
"Keys": [
"ClassA"
],
"Title": "新機能XXを開発する2",
"Body": "ボディ2",
"CompletionTime": "2018/3/31",
"ProcessId": 1,
"ClassHash": {
"ClassA": "RC0001",
"ClassB": "分類2",
"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..."
}
},
"VerUp": true
}
(b)複合キーの場合¶
Keys パラメータに複数の項目名を設定した場合、Keys に指定したすべての項目について、パラメータで指定した値と一致するレコードを検索します。
下記の例では、「ClassA」項目の値が "RC0002" かつ、「ClassB」項目の値が "01" のレコードを検索します。
JSON¶
{
"ApiVersion": 1.1,
"ApiKey": "ad7816s5sD2safFafaD...",
"SsCache": true,
"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..."
}
},
"VerUp": true
}
レスポンス¶
下記の形式のjsonデータが返却されます。
レコードが新規作成された場合¶
{
"Id": 12345,
"StatusCode": 200,
"LimitPerDate": 10000,
"LimitRemaining": 9994,
"Message": "\" 新機能XXを開発する2 \" を作成しました。"
}
レコードが更新された場合¶
{
"Id": 12345,
"StatusCode": 200,
"LimitPerDate": 10000,
"LimitRemaining": 9994,
"Message": "\" 新機能XXを開発する2 \" を更新しました。"
}
作成または更新できなかった場合¶
サンプルコード¶
コード内の【 ... 】 は適宜修正してください¶
1. ファイル名からUpsertキーを取得しUpsertを実行する
任意のフォルダに格納されたファイルを読み取り、ファイル名よりUpsertのキー情報を取得しUpsertを実行します。
実務での使いどころ¶
スキャンした契約書や図面などを、ファイル名に付けた管理番号(KC001 など)で、該当する案件のレコードへまとめて添付したいときに使えます。管理番号のレコードが無ければ新しく作るので、紙の書類の電子化やファイルサーバからの移行で、1 件ずつ添付する手間を省けます。
本サンプルでは、以下のようなファイル名基準とし、”KC”+数字をキー項目として判定します。
KC001_XXXXX.txt
→"KC001"がUpsertキー
実行前¶
登録対象のテーブルの状態、KC001、KC002のレコードが存在

実行後¶
Python(api_record_upsert_p1.py)¶
# WebサイトやAPIと通信するためのライブラリ
import requests
# 画像をBase64化するためのライブラリ
import base64
# JSON操作のためのライブラリ
import json
# ファイル操作や正規表現のためのライブラリ
import mimetypes
# その他標準ライブラリ
import re
# データ構造操作のためのライブラリ
from collections import defaultdict
# ファイルパス操作のためのライブラリ
from pathlib import Path
# 接続先URL
BASE_URL = "【URL】"
# サイトID
SITE_ID = 【サイトID】
# APIキー
API_KEY = "【APIキー】"
# 対象フォルダ
TARGET_FOLDER = r"【パス】"
# キーコード抽出用正規表現
KEY_REGEX = re.compile(r"^(KC\d+)$")
# Upsert のキー項目
UPSERT_KEYS = ["ClassA"]
def extract_keycode(filename: str) -> str | None:
# KC001_FILENAME.txt -> KC001 / ルール外は None
if "_" not in filename:
return None
head = filename.split("_", 1)[0].strip()
if not head:
return None
m = KEY_REGEX.match(head)
return m.group(1) if m else None
def file_to_attachment_obj(path: Path) -> dict:
# Pleasanter AttachmentsA の要素を作る
ctype, _ = mimetypes.guess_type(path.name)
if not ctype:
ctype = "application/octet-stream"
b64 = base64.b64encode(path.read_bytes()).decode("ascii")
return {
"ContentType": ctype,
"Name": path.name,
"Base64": b64,
}
def get_existing_keycodes(session: requests.Session) -> set[str]:
# テーブルにすでにあるキーコード(ClassA)を、1回分ずつ取得してまとめる
url = f"{BASE_URL}/api/items/{SITE_ID}/get"
keycodes: set[str] = set()
offset = 0
while True:
payload = {"ApiVersion": 1.1, "ApiKey": API_KEY, "Offset": offset}
r = session.post(url, data=json.dumps(payload))
if not r.ok:
raise RuntimeError(f"レコード取得失敗 HTTP {r.status_code}\n{r.text}")
response = r.json()["Response"]
rows = response.get("Data", [])
for row in rows:
keycode = (row.get("ClassHash") or {}).get("ClassA")
if keycode:
keycodes.add(keycode)
offset += len(rows)
if not rows or offset >= response.get("TotalCount", 0):
return keycodes
def upsert_attachments(
session: requests.Session, keycode: str, attachments: list[dict], is_new: bool
) -> dict:
url = f"{BASE_URL}/api/items/{SITE_ID}/upsert"
payload = {
"ApiVersion": 1.1,
"ApiKey": API_KEY,
"Keys": UPSERT_KEYS,
"ClassHash": {
"ClassA": keycode,
},
"AttachmentsHash": {"AttachmentsA": attachments},
}
# 新しく作るレコードだけ、タイトルにキーコードを入れる(既存のレコードのタイトルは変えない)
if is_new:
payload["Title"] = keycode
r = session.post(url, data=json.dumps(payload))
if not r.ok:
raise RuntimeError(f"Upsert失敗 key={keycode} HTTP {r.status_code}\n{r.text}")
return r.json()
def main():
folder = Path(TARGET_FOLDER)
if not folder.is_dir():
raise SystemExit(f"フォルダが見つかりません: {folder}")
# キーコードごとに添付をまとめる(同一KCに複数ファイルがある場合もまとめて登録)
grouped: dict[str, list[Path]] = defaultdict(list)
for p in folder.iterdir():
if not p.is_file():
continue
keycode = extract_keycode(p.name)
if not keycode:
# ルール外は処理対象外
continue
grouped[keycode].append(p)
if not grouped:
print("処理対象ファイルなし(命名規則に一致するファイルがありません)")
return
session = requests.Session()
session.headers.update({"Content-Type": "application/json"})
# すでにあるキーコードを先に調べ、新しく作るレコードかどうかを判定する
existing = get_existing_keycodes(session)
for keycode, paths in grouped.items():
attachments = [file_to_attachment_obj(p) for p in paths]
try:
res = upsert_attachments(session, keycode, attachments, keycode not in existing)
# Upsertのレスポンスを表示
print(f"OK: key={keycode} 添付={len(attachments)}件 / response={res}")
except Exception as e:
print(f"NG: key={keycode} 添付={len(paths)}件")
print(e)
if __name__ == "__main__":
main()
実行¶
実行結果¶
エラー時の確認事項¶
・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'に変更されました。
対応バージョン¶
| 対応バージョン | 内容 |
|---|---|
| 1.5.6.0 以降 | VerUpを追加 |
-
{サーバ名}、{サイトID}の部分は、適宜、環境に合わせて編集してください。Pleasanter.netの場合は
https://pleasanter.net/fs/api/items/{サイトID}/upsertの形式です。 ↩


