コンテンツにスキップ

レコード作成

概要

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)
実行
>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'に変更されました。


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

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