## 概要 APIを使用して、レコードを作成・更新します。 ・ 指定したキー項目が一致するレコードがある場合：該当レコードを更新 ・ 一致するレコードがない場合：レコードを新規作成 ## 制限事項 1. 対象の「レコード」に「作成」および「更新」権限が必要です。 1. [Wiki](/ja/manual/wiki)では使用できません。 ## 事前準備 APIの操作を行う前に[APIキーの作成](/manual/api-key)を実施してください。 ## リクエスト 下記のリクエスト形式で、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を指定することで[内容](/ja/manual/table-management-body)、[コメント](/ja/manual/table-management-comments)、[説明](/ja/manual/table-management-column-description)項目に画像を挿入することが可能です。 更新系のAPI（update／upsert）で本機能によるレコード更新を行う場合、既存レコードの該当項目は[内容](/ja/manual/table-management-body)、[説明](/ja/manual/table-management-column-description)項目では上書き、[コメント](/ja/manual/table-management-comments)項目では追加となります。また、更新系のAPIで[内容](/ja/manual/table-management-body)、[説明](/ja/manual/table-management-column-description)項目に登録する文字列を指定するBodyやDescriptionHashを省略した状態でImageHashのみを指定すると、上書きではなく追加となります。 ##### ImageHashの指定方法 <style type="text/css"> .tg {border-collapse:collapse;border-spacing:0;} .tg td{border-color:black;border-style:solid;border-width:1px;font-family:Arial, sans-serif;font-size:14px; overflow:hidden;padding:10px 5px;word-break:normal;} .tg th{border-color:black;border-style:solid;border-width:1px;font-family:Arial, sans-serif;font-size:14px; font-weight:normal;overflow:hidden;padding:10px 5px;word-break:normal;} .tg .tg-0lax{text-align:left;vertical-align:top} </style> <table class="tg"> <thead> <tr> <th class="tg-0lax">第1階層</th> <th class="tg-0lax">第2階層</th> <th class="tg-0lax">第3階層</th> <th class="tg-0lax">説明</th> <th class="tg-0lax">例</th> </tr> </thead> <tbody> <tr> <td class="tg-0lax" rowspan="9">ImageHash</td> <td class="tg-0lax" rowspan="6">Body</td> <td class="tg-0lax">HeadNewLine</td> <td class="tg-0lax">画像を挿入する際の先頭の改行有無をtrue/falseで指定します。省略した場合は改行無しになります。</td> <td class="tg-0lax">true</td> </tr> <tr> <td class="tg-0lax">EndNewLine</td> <td class="tg-0lax">画像を挿入する際の末尾の改行有無をtrue/falseで指定します。省略した場合は改行無しになります。</td> <td class="tg-0lax">true</td> </tr> <tr> <td class="tg-0lax">Position</td> <td class="tg-0lax">同じリクエスト内で対象項目に文字列を設定する場合に画像を何文字目に挿入するかを数値で指定します。-1を指定した場合および省略した場合は末尾に挿入されます。</td> <td class="tg-0lax">3</td> </tr> <tr> <td class="tg-0lax">Alt</td> <td class="tg-0lax">alt属性（Webブラウザで画像が表示できないときに、画像の代わりに表示されるテキスト）に挿入する文字列を指定します。省略した場合は「image」が設定されます。</td> <td class="tg-0lax">hayato</td> </tr> <tr> <td class="tg-0lax">Extension</td> <td class="tg-0lax">Binariesテーブルに登録するファイル拡張子を指定します。省略した場合は「.png」が設定されます。</td> <td class="tg-0lax">.jpeg</td> </tr> <tr> <td class="tg-0lax">Base64</td> <td class="tg-0lax">Base64エンコードした画像のバイナリデータを文字列で指定します。ImageHashを指定する場合、省略はできません。</td> <td class="tg-0lax">iVBORw0KG…（以下略）</td> </tr> <tr> <td class="tg-0lax">Comments</td> <td class="tg-0lax">（同上）</td> <td class="tg-0lax">（同上）</td> <td class="tg-0lax">-</td> </tr> <tr> <td class="tg-0lax">DescriptionA</td> <td class="tg-0lax">（同上）</td> <td class="tg-0lax">（同上）</td> <td class="tg-0lax">-</td> </tr> <tr> <td class="tg-0lax">DescriptionB</td> <td class="tg-0lax">（同上）</td> <td class="tg-0lax">（同上）</td> <td class="tg-0lax">-</td> </tr> </tbody> </table> #### APIによるプロセスの実行について リクエストデータに、プロセスIDを指定し、プロセスを実行することが可能です。 ##### 事前準備 事前に[プロセス](/ja/manual/process)を設定してください。 ##### 制限事項 APIからプロセスを実行する場合、プロセスで設定した入力検証は適用されません。 ##### プロセスの指定方法 ProccessId または ProccessIds のいずれか一方を設定してください。 両方が設定された場合は、ProccessIds が有効となります。 ProccessIds を指定した場合、リストで指定された複数のプロセスIDは、事前に設定されている[プロセス](/ja/manual/process)一覧の表示順に従って実行されます。 |設定項目|説明|例| |:--|:--|:--| |ProccessId|プロセスのIDを指定します。|1| |ProccessIds|複数のプロセスのIDを指定します。|[1,2,3]| ### (a)単一キーの場合 Keys パラメータにキーとなる項目の項目名を配列形式で設定します。Keys に指定した項目について、パラメータで指定した値と一致するレコードを検索します。 下記の例では、「ClassA」項目の値が "RC0001" のレコードを検索します。 レコードを検索した結果に応じて下記の処理が実行されます。 1. 対象のレコードが存在しなかった場合: レコードが新規作成されます。 1. 対象のレコードが１件存在した場合: そのレコードが更新されます。 1. 対象のレコードが複数件存在した場合: レコードの作成・更新は行われず、エラーレスポンスが返却されます。 #### JSON ```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 ```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 \" を作成しました。" } ``` ### レコードが更新された場合 ```json { "Id": 12345, "StatusCode": 200, "LimitPerDate": 10000, "LimitRemaining": 9994, "Message": "\" 新機能XXを開発する2 \" を更新しました。" } ``` ### 作成または更新できなかった場合 ```json { "Id": 12345, "StatusCode": 401, "Message": "認証できませんでした。" } ``` ## サンプルコード ##### コード内の【 ... 】 は適宜修正してください。 <details> <summary>1. ファイル名からUpsertキーを取得しUpsertを実行する</summary> 任意のフォルダに格納されたファイルを読み取り、ファイル名よりUpsertのキー情報を取得しUpsertを実行します。 本サンプルでは、以下のようなファイル名基準とし、”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 upsert_attachments( session: requests.Session, keycode: str, attachments: list[dict] ) -> 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}, } 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"}) for keycode, paths in grouped.items(): attachments = [file_to_attachment_obj(p) for p in paths] try: res = upsert_attachments(session, keycode, attachments) # 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() ``` ##### 実行 ``` >python api_record_upsert_p1.py ``` ##### 実行結果 ``` OK: key=KC001 添付=2件 / response={'Id': 9999, 'StatusCode': 200, 'Message': '" KC001 " を更新しました。'} OK: key=KC002 添付=1件 / response={'Id': 9999, 'StatusCode': 200, 'Message': '" KC002 " を更新しました。'} OK: key=KC003 添付=1件 / response={'Id': 9999, 'StatusCode': 200, 'Message': '" KC003 " を更新しました。'} ・・・・ ``` </details> ## エラー時の確認事項 [・API使用時の注意点やエラーが発生する場合の確認事項](/manual/faq-api) [・FAQ:変更後の設定ファイルやAPIリクエスト(JSON形式)が正しく認識されない場合の確認事項](/manual/faq-json-format) ## 仕様変更について **※ 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'に変更されました。