レコード作成

2019年5月2日2026年10月11日

概要¶

APIを使用して新規にレコードを作成することができます。

事前準備¶

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

リクエスト¶

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

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

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

設定値¶

設定値にはスクリプトの$p.apiCreateおよびサーバスクリプトのitems.Createも指定できます。

パラメータ名	型	必須	概要
ApiVersion	decimal		APIのバージョン。
ApiKey	string	○¹	事前に作成したAPIキー。
SsCache	bool		サイト設定のキャッシュを有効化・無効化する。詳細は「JSONデータレイアウト：共通」を参照。
JSONデータレイアウト	object	○	作成するレコードの情報。詳細は「JSONデータレイアウト：共通」および「JSONデータレイアウト：Item」を参照。

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

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

How to Specify ImageHash¶

1st Level	2nd Level	3rd Level	Description	Example
ImageHash	Body	HeadNewLine	Specify whether to insert a newline at the beginning of the image with true/false. If omitted, there will be no newline.	true
		EndNewLine	Specifies whether to insert a newline at the end of the image with true/false. If omitted, there will be no newline.	true
		Position	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.	3
		Alt	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.	hayato
		Extension	Specifies the file extension to register in the Binaries table. If omitted, ".png" will be set.	.jpeg
		Base64	Specify the Base64 encoded binary data of the image as a string. If you specify ImageHash, this cannot be omitted.	iVBORw0KG…（the following omitted）
	Comments	（same as above）	（same as above）	-
	DescriptionA	（same as above）	（same as above）	-
	DescriptionB	（same as above）	（same as above）	-

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

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

Preconfiguration¶

Please set up the "Process" in advance.

Limitations¶

When executing a process via the API, input validation set for the process

Process Specifying Method¶

Either ProccessId or ProccessIds should be set. If both are set, ProccessIds is applied.
Note that when ProccessIds is set, the specified multiple process IDs will be executed in the order in which they appear in the list of "Process" set in advance.

Setting Item	Description	Example
ProccessId	Specify the ID of the process.	1
ProccessIds	Specify IDs for multiple processes.	[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)

実行¶

>python api_record_create_p1.py

実行結果¶

200 {"Id":9999,"StatusCode":200,"Message":"\" サンプル案件F \" を作成しました。"}

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)

実行¶

>python api_record_create_p2.py

実行結果¶

200 {"Id":9999,"StatusCode":200,"Message":"\" 添付付きレコード \" を作成しました。"}

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)

実行¶

>python api_record_create_p3.py

実行結果¶

200 {"Id":9999,"StatusCode":200,"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'に変更されました。

APIキーはAPIでは指定必須。スクリプト、サーバスクリプトは任意指定で、指定した場合はAPIキーのユーザの権限で処理を実行。 ↩

レコード作成

概要¶

事前準備¶

リクエスト¶

設定値¶

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

How to Specify ImageHash¶

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

Preconfiguration¶

Limitations¶

Process Specifying Method¶

JSON¶

レスポンス¶

JSON¶

使用例¶

コード内の【 ... 】 は適宜修正してください。¶

Python(api_record_create_p1.py)¶

実行¶

実行結果¶

Python(api_record_create_p2.py)¶

実行¶

実行結果¶

Python(api_record_create_p3.py)¶

実行¶

実行結果¶

エラー時の確認事項¶

仕様変更について¶

コード内の【 ... 】は適宜修正してください。¶