開発者向け機能：スクリプト：$p.apiCreate
## 概要
AjaxのPOSTリクエストにより、新規レコードを作成します。
## 構文
##### JavaScript
```
$p.apiCreate({
id: (サイトID),
data: {
項目名: '(値)'
},
done: (任意の処理),
fail: (任意の処理),
always: (任意の処理)
});
```
## パラメータ
|パラメータ名|型|必須|概要|
|:--|:--|:--|:--|
|id|long|○|任意のサイトのID|
|data|object|○|作成するレコードの条件等をJSON形式で指定。JSONの仕様は [レコード作成API](/manual/api-record-create)を参照。|
|done|function|○|API通信成功時の処理|
|fail|function||API通信失敗時の処理|
|always|function||API通信完了時の処理|
## 使用例
以下のサンプルコードは、サイトID:123のテーブルにタイトルが"コーヒー"、分類Aが"ブラック" のレコードを作成します。
##### JavaScript
```
$p.apiCreate({
id: 123,
data: {
Title: 'コーヒー',
ClassHash: {
ClassA: 'ブラック'
}
},
done: function (data) {
$p.clearMessage();
const message = {
Css: 'alert-success',
Text: '新規レコードを作成しました'
};
$p.setMessage('#Message',JSON.stringify(message));
},
fail: function (data) {
console.log(data);
}
});
```
## サンプルコード
##### コード内の【 ... 】 は適宜修正してください。
<details>
<summary>1. レコード作成</summary>
レコードを新規作成します。
##### JavaScript
```
// 作成先のサイトID
const siteId = 【サイトID】;
$p.apiCreate({
id: siteId,
data: {
ApiVersion: 1.1,
Title: 'サンプル案件_P1',
Status: 200,
ClassHash: { ClassA: '問い合わせ' },
DateHash: { DateA: '2025/1/10' },
NumHash: { NumA: 5 },
},
done: function (data) {
console.log('レコード作成成功');
},
fail: function (data) {
console.log('レコード作成失敗');
},
});
```
##### 実行結果
```
レコード作成成功
```
</details>
<details>
<summary>2. 全ユーザーを対象に、重複条件に一致しない人だけレコードを一括作成する</summary>
このスクリプトは、指定したサイトの全ユーザー（テナント管理者を除く）を対象に、次の処理を自動実行します。
1.**既存データの確認**
指定サイトの既存レコードを全件取得します。そのうえで、ユーザーごとに「重複判定ルール」に当てはまるレコードがすでに存在するかを確認します。
（サンプルの重複判定ルール：レコードの **Owner が対象ユーザー本人**で、かつ **ClassA が "案内区分A"** になっていること）
2.**条件付き一括作成**
該当レコードが**ない**（未登録の）ユーザー：新規レコードを作成します。
該当レコードが**ある**（登録済みの）ユーザー：何もしません。
※類似の機能として [$p.apiUpsert](https://pleasanter.org/ja/manual/script-api-upsert)（キー項目が一致すれば更新、一致しなければ新規作成）がありますが、両者は用途が異なります。
使い分けの目安
| 観点 | このスクリプト | $p.apiUpsert |
|---|---|---|
| 何をもとに動くか | ユーザー一覧を起点に、全ユーザー分をチェックする | 渡したデータ（1件〜複数件）を起点に処理する |
| すでにレコードがある人・データはどうなるか | 何もしない（既存レコードはそのまま） | 内容を最新の状態に更新する |
| まだレコードがない人・データはどうなるか | 新規作成する | 新規作成する |
| こんなときに向いている | 「まだ1件も登録がない人にだけ配りたい」時（初期配布・登録漏れの棚卸し） | 「常に最新の内容に保ちたい」時（外部データとの同期・定期反映） |
##### JavaScript
```
// ==========================================
// 設定エリア
// ==========================================
const CONFIG = {
SITE_ID: 【サイトID】,
// ここで重複判定ルールを定義する(サンプルはOwner+ClassA)
isDuplicate: (record, user) => {
return String(record.Owner) === String(user.UserId) &&
String(record.ClassHash.ClassA) === "案内区分A"; // 必要に応じて条件を追加
},
// 作成するデータの内容
createData: (user) => ({
Title: `${user.Name}様への連絡事項`,
Status: 100,
Owner: user.UserId,
ClassHash: { ClassA: '案内区分A' }
})
};
// ==========================================
// 共通処理：全件取得
// Offsetを「実際に取得した件数」ぶんずつ進めながら、
// 取得件数が0件になるかTotalCountに達するまで繰り返す
// ==========================================
function fetchAll(apiFunc, options) {
return new Promise((resolve, reject) => {
let allData = [];
const fetchPage = (offset) => {
const data = Object.assign({}, options.data, {
View: Object.assign({}, (options.data && options.data.View) || {}, {
Offset: offset
})
});
apiFunc(Object.assign({}, options, {
data: data,
done: (res) => {
const records = res.Response.Data;
allData = allData.concat(records);
const totalCount = res.Response.TotalCount;
const nextOffset = offset + records.length; // 実際の取得件数ぶん進める
if (records.length > 0 && nextOffset < totalCount) {
fetchPage(nextOffset); // まだ取得していないレコードが残っているので続けて取得
} else {
resolve(allData); // 全件取得完了
}
},
fail: (res) => reject(res)
}));
};
fetchPage(0);
});
}
// ==========================================
// 実行処理
// ==========================================
(async () => {
try {
// 1. 既存レコードを全件取得
const existingRecords = await fetchAll($p.apiGet, { id: CONFIG.SITE_ID });
// 2. ユーザー一覧を全件取得
const allUsers = await fetchAll($p.apiUsersGet, {});
// 3. テナント管理者を除き、未登録ユーザーのみ抽出
const targets = allUsers.filter(user =>
!user.TenantManager &&
!existingRecords.some(rec => CONFIG.isDuplicate(rec, user))
);
if (targets.length === 0) {
console.log("(info)全員登録済みです。");
return;
}
targets.forEach(user => {
$p.apiCreate({
id: CONFIG.SITE_ID,
data: CONFIG.createData(user),
done: () => console.log(`(info)作成完了: ${user.Name}`),
fail: (res) => console.error(`(info)作成失敗: ${user.Name}`, res)
});
});
} catch (err) {
console.error("(error)処理中にエラーが発生しました", err);
}
})();
```
##### 実行結果
・存在しない場合
```
(info)作成完了: 社員A
(info)作成完了: 社員B
(info)作成完了: 社員C
```
・存在する場合
```
(info)全員登録済みです。
```
</details>
