## 概要 APIを使用してレコードを作成または更新する事ができます。 指定したキー項目が一致するレコードがある場合はそのレコードを更新、一致するレコードがない場合は新規作成を行います。 ## 制限事項 1. 対象の「レコード」に「作成」および「更新」権限が必要です。 ## 事前準備 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)複合キーの場合 をご参照ください。 #### Insert Image by API You can insert an image into the "[Body](/en/manual/table-management-body)", "[Comment](/en/manual/table-management-comments)" and "[Description](/en/manual/table-management-column-description)" column by specifying an ImageHash in the Body. When updating a record using this function with an update API (update/upsert), the corresponding column of the existing record will be overwritten in the "[Body](/en/manual/table-management-body)" and "[Description](/en/manual/table-management-column-description)" columns, and added in the "[Comment](/en/manual/table-management-comments)" column. In addition, if you specify only ImageHash without specifying Body or DescriptionHash, which specify the string to be registered in the description field in an update API, it will be added rather than overwritten. ##### How to Specify 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">1st Level</th> <th class="tg-0lax">2nd Level</th> <th class="tg-0lax">3rd Level</th> <th class="tg-0lax">Description</th> <th class="tg-0lax">Example</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">Specify whether to insert a newline at the beginning of the image with true/false. If omitted, there will be no newline.</td> <td class="tg-0lax">true</td> </tr> <tr> <td class="tg-0lax">EndNewLine</td> <td class="tg-0lax">Specifies whether to insert a newline at the end of the image with true/false. If omitted, there will be no newline.</td> <td class="tg-0lax">true</td> </tr> <tr> <td class="tg-0lax">Position</td> <td class="tg-0lax">Specifies the position of the image to insert when setting a string in the target item in the same request. If -1 is specified or omitted, it will be inserted at the end.</td> <td class="tg-0lax">3</td> </tr> <tr> <td class="tg-0lax">Alt</td> <td class="tg-0lax">Specifies the string to insert into the alt attribute (text displayed instead of the image when the image cannot be displayed in the web browser). If omitted, "image" will be set.</td> <td class="tg-0lax">hayato</td> </tr> <tr> <td class="tg-0lax">Extension</td> <td class="tg-0lax">Specifies the file extension to register in the Binaries table. If omitted, ".png" will be set.</td> <td class="tg-0lax">.jpeg</td> </tr> <tr> <td class="tg-0lax">Base64</td> <td class="tg-0lax">Specify the Base64 encoded binary data of the image as a string. If you specify ImageHash, this cannot be omitted.</td> <td class="tg-0lax">iVBORw0KG…（the following omitted）</td> </tr> <tr> <td class="tg-0lax">Comments</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">-</td> </tr> <tr> <td class="tg-0lax">DescriptionA</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">-</td> </tr> <tr> <td class="tg-0lax">DescriptionB</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">-</td> </tr> </tbody> </table> #### APIによるプロセスの実行について リクエストデータに、プロセスIDを指定し、プロセスを実行することが可能です。 ##### 事前準備 事前に[プロセス](/ja/manual/process)を設定してください。 ##### 制限事項 APIからプロセスを実行する場合、プロセスで設定した入力検証は適用されません。 ##### プロセスの指定方法 |設定項目|説明|例| |:--|:--|:--| |ProccessId|プロセスのIDを指定します。|1| #### (a)単一キーの場合 Keys パラメータにキーとなる項目の項目名を配列形式で設定します。Keys に指定した項目について、パラメータで指定した値と一致するレコードを検索します。 下記の例では、「ClassA」項目の値が "RC0001" のレコードを検索します。 レコードを検索した結果に応じて下記の処理が実行されます。 1. 対象のレコードが存在しなかった場合: レコードが新規作成されます。 1. 対象のレコードが１件存在した場合: そのレコードが更新されます。 1. 対象のレコードが複数件存在した場合: レコードの作成・更新は行われず、エラーレスポンスが返却されます。 ##### 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使用時の注意点やエラーが発生する場合の確認事項](/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'に変更されました。