$p.apiGet
概要¶
指定したサイトのレコード情報を取得します。サイト統合を設定しているテーブルの場合は、統合された各レコードの情報もあわせて取得します。
制限事項¶
- 取得できるレコードの件数はパラメータ設定：Api.jsonの PageSize（デフォルトで200）が最大となります。200件以上のレコードを取得する場合は、「FAQ：APIで200レコードを超えるデータを取得したい」を参照してください。
構文¶
パラメータ¶
| パラメータ名 | 型 | 必須 | 概要 |
|---|---|---|---|
| id | long | ○ | 操作対象のサイトID、またはレコードIDを指定。 |
| data | object | POSTするJSONデータを指定。「JSONデータレイアウト：View」、テーブル種類(TableType)を指定することが可能。指定可能なテーブル種類については下記の "テーブル種類について" をご確認ください。 | |
| done | function | ○ | API通信成功時の処理 |
| fail | function | API通信失敗時の処理 | |
| always | function | API通信完了時の処理 |
テーブル種類について¶
テーブル種類(TableType)に指定可能な値は以下の通りです。
| 値 | 説明 |
|---|---|
| Normal | 指定したサイトのレコード情報を取得する場合に指定します。取得するレコード情報は履歴が最新バージョンです。また、こちらの値はTableTypeの既定値で、TableTypeを指定しない場合は、内部ではこの値が設定されて処理が行われます。 |
| History | 指定したサイトのレコードの履歴情報を取得する場合に指定します。取得するレコード情報は履歴が過去バージョン(最新バージョンは含まない)です。 |
| NormalAndHistory | 指定したサイトのレコード情報と履歴情報を合わせて取得する場合に指定します。取得するレコード情報は履歴が全てのバージョンです。 |
使用例①¶
POSTするデータに"View"のJSONデータレイアウトを指定する場合は以下のように記述します。
$p.apiGet({
id: 123,
data: {
View: {
ApiDataType: "KeyValues",
GridColumns: ["Title", "ClassA"]
}
},
done: function (data) {
alert('通信が成功しました。');
}
});
Tip
"View"のレイアウトについてはJSONデータレイアウト：Viewを確認してください。
使用例②¶
POSTするデータにテーブル種類"TableType"を指定する場合は以下のように記述します。
$p.apiGet({
id: 123,
data: {
TableType: 'History'
},
done: function (data) {
alert('通信が成功しました。');
}
});
使用例③¶
POSTするデータに"View"のJSONデータレイアウト、テーブル種類"TableType"を指定する場合は以下のように記述します。
$p.apiGet({
id: 123,
data: {
View: {
ColumnFilterHash:{
ClassA: '中野区'
}
},
TableType: 'History'
},
done: function (data) {
console.log(data);
}
});
サンプルコード¶
Note
コード内の【 ... 】は適宜修正してください。
1. レコードIDを指定して取得する
レコードIDを指定して取得します。
実務での使いどころ¶
一覧で選んだ問い合わせのレコードIDから、件名や分類を取り出して別のテーブルへ転記する、といった場面に使えます。取得するのは 1 件のみのため、ボタンを押したときや画面を開いたときに、関連する 1 件の内容を参照したい処理に向いています。
// 取得対象のレコードID
const recordId = 【レコードID】;
$p.apiGet({
id: recordId,
done: function (data) {
const records = data.Response.Data;
if (records.length === 0) {
console.log('レコードが見つかりませんでした。recordId=' + recordId);
return;
}
const item = records[0];
console.log(`${item.Title} ${item.ClassHash.ClassA}`);
},
fail: function (data) {
console.log('レコード取得に失敗しました。');
},
});
実行結果¶
2. サイトIDを指定しレコード全件取得する
サイトIDを指定し、レコード全件します。
実務での使いどころ¶
テーブルに登録されている案件を一覧にして集計したり、件数を数えたりする場面に使えます。1 回に取得できるのは 200 件までです。それより多いテーブルでは「6. 200件を超えるレコードを取得する」の方法を使ってください。
// 取得対象のサイトID
const siteId = 【サイトID】;
$p.apiGet({
id: siteId,
done: function (data) {
const records = data.Response.Data;
records.forEach(function (item) {
console.log(`${item.Title} ${item.ClassHash.ClassA}`);
});
},
fail: function (data) {
console.log('レコード取得に失敗しました。');
},
});
実行結果¶
3. 日付の期間を指定しレコードを取得する
日付の期間を指定しレコードを取得します。
実務での使いどころ¶
「今週受け付けた問い合わせ」「今月が期限の案件」のように、日付の範囲で対象を絞り込みたい場面に使えます。start と end を当日の日付から計算するようにすれば、毎回期間を書き替えずに使えます。
// 取得対象のサイトID
const siteId = 【サイトID】;
// 取得対象の期間（DateA が start〜end の範囲内のレコードを取得）
const start = '2025/01/10';
const end = '2025/01/12';
$p.apiGet({
id: siteId,
data: {
View: {
ColumnFilterHash: {
// 日付の範囲指定（開始日時, 終了日時）
DateA: `["${start} 00:00:00, ${end} 23:59:59"]`,
},
ColumnSorterHash: {
DateA: 'asc', // 日付の昇順で並べ替え
},
},
},
done: function (data) {
const records = data.Response.Data;
records.forEach(function (item) {
console.log(`${item.Title} ${item.ClassHash.ClassA} ${item.DateHash.DateA}`);
});
},
fail: function (data) {
console.log('レコード取得に失敗しました。');
},
});
実行結果¶
4. ステータスコードを指定し取得する
ステータスを指定し取得します。
実務での使いどころ¶
「未着手」と「実施中」のように、まだ完了していないレコードに絞って取り出し、残件を確認したい場面に使えます。ステータスコードは、「テーブルの管理」の「エディタ」タブで「状況」項目の選択肢一覧を開くと確認できます。
// 取得対象のサイトID
const siteId = 【サイトID】;
// 取得対象のステータスコード（複数指定 → OR 検索）
const statusCodes = `["100","200"]`;
$p.apiGet({
id: siteId,
data: {
View: {
ColumnFilterHash: {
Status: statusCodes, // ステータスで絞り込み（OR）
},
ColumnSorterHash: {
DateA: 'asc',
},
},
},
done: function (data) {
const records = data.Response.Data;
records.forEach(function (item) {
console.log(`${item.Title} ${item.ClassHash.ClassA} ${item.Status}`);
});
},
fail: function (data) {
console.log('レコード取得に失敗しました。');
},
});
実行結果¶
5. 文字列で検索（部分一致）し取得する
文字列で検索（部分一致）し取得します。
実務での使いどころ¶
内容に「リリース」を含む要望に絞って拾い出すように、キーワードで関連するレコードを探したい場面に使えます。入力欄に入れた語句を keyword に渡せば、画面から簡単な検索をする仕組みにも使えます。
// 取得対象のサイトID
const siteId = 【サイトID】;
// 検索する文字列（DescriptionA に対して部分一致）
const keyword = 'リリース';
$p.apiGet({
id: siteId,
data: {
View: {
ColumnFilterHash: {
DescriptionA: keyword, // 検索対象の項目と文字列
},
ColumnFilterSearchTypes: {
DescriptionA: 'PartialMatch', // 部分一致
},
ColumnSorterHash: {
DateA: 'asc',
},
},
},
done: function (data) {
const records = data.Response.Data;
records.forEach(function (item) {
console.log(`${item.Title} ${item.ClassHash.ClassA} ${item.DescriptionHash.DescriptionA}`);
});
},
fail: function (data) {
console.log('レコード取得に失敗しました。');
},
});
実行結果¶
6. 200件を超えるレコードを取得する
200件を超えるレコードを取得します。
実務での使いどころ¶
過去の問い合わせを全件まとめて集計する、件数の多いテーブルからデータを書き出す、といった場面に使えます。$p.apiGet は 1 回に 200 件までしか返さないため、Offset をずらしながら全件を取り切ります。件数が多いほど時間がかかるので、画面を開くたびに実行するのではなく、ボタンを押したときに実行するなどの使い方が向いています。
// 取得対象のサイトID
const siteId = 【サイトID】;
// 取得した全レコードを蓄積する配列
const allItems = [];
// offset の位置から1ページ分を取得する（取得後に次ページを再帰呼び出し）
function fetchPage(offset) {
$p.apiGet({
id: siteId,
data: {
Offset: offset, // 取得開始位置
},
done: function (data) {
const records = data.Response.Data;
// 取得件数が0になったら終了し、全件をまとめて処理する
if (!records || records.length === 0) {
console.log(`最終的な取得件数: ${allItems.length} 件`);
allItems.forEach(function (item) {
console.log(`${item.Title} ${item.ClassHash.ClassA}`);
});
return;
}
// 今回分を配列に追加
records.forEach(function (item) {
allItems.push(item);
});
console.log(`Offset=${offset}, 取得件数=${records.length}`);
// Offset を「今回取得した件数ぶん」進めて次ページを取得
fetchPage(offset + records.length);
},
fail: function (data) {
console.log('レコード取得に失敗しました。offset=' + offset);
},
});
}
// 先頭（Offset=0）から取得開始
fetchPage(0);