レコード作成
概要¶
APIを使用して新規にレコードを作成することができます。
事前準備¶
APIの操作を行う前にAPIキーの作成を実施してください。
リクエスト¶
下記のリクエスト形式で、JSONデータを送信します。
| 設定項目 | 値 |
|---|---|
| HTTPメソッド | POST |
| Content-Type | application/json |
| 文字コード | UTF-8 |
| URL | http://{サーバ名}/api/items/{サイトID}/create1 |
| Body | 以下のJSONデータを参考のこと |
設定値¶
設定値にはスクリプトの$p.apiCreateおよびサーバスクリプトのitems.Createも指定できます。
| パラメータ名 | 型 | 必須 | 概要 |
|---|---|---|---|
| ApiVersion | decimal | APIのバージョン。 | |
| ApiKey | string | ○2 | 事前に作成したAPIキー。 |
| SsCache | bool | サイト設定のキャッシュを有効化・無効化する。詳細は「JSONデータレイアウト:共通」を参照。 | |
| JSONデータレイアウト | object | ○ | 作成するレコードの情報。詳細は「JSONデータレイアウト:共通」および「JSONデータレイアウト:Item」を参照。 |
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] |
JSON¶
{
"ApiVersion": 1.1,
"ApiKey": "XXXXXXXXXX...",
"SsCache": true,
"Title": "新機能XXを開発する",
"Body": "ボディ",
"CompletionTime": "2018/3/31",
"ProcessId": 1,
"ClassHash": {
"ClassA": "分類",
"ClassB": "未分類",
"ClassC": "その他"
},
"NumHash": {
"NumA": 100,
"NumB": 200
},
"DateHash": {
"DateA": "2019/01/01",
"DateB": "2020/01/01"
},
"DescriptionHash": {
"DescriptionA": "説明",
"DescriptionB": "概要",
"DescriptionC": "補足"
},
"CheckHash": {
"CheckA": true,
"CheckB": false
},
"AttachmentsHash": {
"AttachmentsA": [
{
"ContentType": "text/plain",
"Name": "Readme.txt",
"Base64": "5yY5Trfi4..."
}
]
},
"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": 9996,
"Message": "\" 新機能XXを開発する \" を作成しました。"
}
使用例¶
コード内の【 ... 】 は適宜修正してください。¶
1. 添付ファイル・画像を含まないレコードを作成する
添付ファイル・画像を含まないレコードを作成します。
Python(api_record_create_p1.py)¶
import requests
# サーバ名、APIキー、サイトID
BASE_URL = "【サーバ名】"
API_KEY = "【APIキー】"
SITE_ID = 【サイトID】
url = f"{BASE_URL}/api/items/{SITE_ID}/create"
# 単純レコード作成
payload = {
"ApiVersion": 1.1,
"ApiKey": API_KEY,
"Title": "サンプル案件F",
"Status": 200,
"ClassHash": {"ClassA": "障害"},
"DateHash": {"DateA": "2025/1/20", "DateB": "2025/1/25"},
"NumHash": {"NumA": 20, "NumB": 3},
}
res = requests.post(url, json=payload, headers={"Content-Type": "application/json"})
print(res.status_code, res.text)
実行¶
実行結果¶
2. 添付ファイルを含むレコードを作成する
添付ファイルを含むレコードを作成します。
Python(api_record_create_p2.py)¶
import requests
import base64
# サーバ名、APIキー、サイトID
BASE_URL = "【サーバ名】"
API_KEY = "【APIキー】"
SITE_ID = 【サイトID】
FILE_NAME = "【添付ファイル名】"
CONTENT_TYPE = "【ファイル形式】"
# 添付ファイルをBase64化
b64 = base64.b64encode(open(FILE_NAME, "rb").read()).decode()
url = f"{BASE_URL}/api/items/{SITE_ID}/create"
# 添付ファイルを含むレコード作成
payload = {
"ApiVersion": 1.1,
"ApiKey": API_KEY,
"Title": "添付付きレコード",
"DescriptionHash": {
"DescriptionA": "添付ファイルを登録するサンプルです",
},
"AttachmentsHash": {
"AttachmentsA": [
{
"ContentType": CONTENT_TYPE,
"Name": FILE_NAME,
"Base64": b64,
}
]
},
}
res = requests.post(url, json=payload, headers={"Content-Type": "application/json"})
print(res.status_code, res.text)
実行¶
実行結果¶
3. 画像を含むレコードを作成する
画像を含むレコードを作成します。
Python(api_record_create_p3.py)¶
import requests
import base64
# サーバ名、APIキー、サイトID
BASE_URL = "【サーバ名】"
API_KEY = "【APIキー】"
SITE_ID = 【サイトID】
FILE_NAME = "【画像ファイル名】"
EXTENSION = "【画像ファイル拡張子】"
# 画像ファイルをBase64化
b64 = base64.b64encode(open(FILE_NAME, "rb").read()).decode()
url = f"{BASE_URL}/api/items/{SITE_ID}/create"
# 画像を含むレコード作成
payload = {
"ApiVersion": 1.1,
"ApiKey": API_KEY,
"Title": "画像付きレコード",
"DescriptionHash": {
"DescriptionA": "画像を登録するサンプルです",
},
"ImageHash": {
"DescriptionA": {
"HeadNewLine": "true",
"EndNewLine": "true",
"Alt": "imageDescriptionA",
"Extension": EXTENSION,
"Base64": b64,
}
},
}
res = requests.post(url, json=payload, headers={"Content-Type": "application/json"})
print(res.status_code, res.text)
実行¶
実行結果¶
エラー時の確認事項¶
・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'に変更されました。
