Pleasanter で ExcelAPI を使うための補助スクリプト

2022 個人アドベントカレンダー の記事です。

これは何

ExcelAPI が Google Spreadsheet で使えるようになったので Pleasanter でも使えるようにしてみる

方針

• WEBSERVICE という補助関数(ヘルパ)を作る
  • URL を指定するのは Excel と同じ
  • ただし 2 つめのパラメータにどの項目をどのパラメータとして利用するか指定する
• いくつかの API で試しているものの、網羅的に確認はしていないのでご寛恕いただきたい

なお ExcelAPI は Access-Control-Allow-Origin の応答ヘッダを持たないので、サーバスクリプトでの実装となります。

サーバスクリプトでの実装

「共通」に置くヘルパ

const WEBSERVICE = (url, options = {}) => {
  const connector = url.includes('?') ? '&' : '?';
  const param = Object.entries(options)
    .reduce((a, c) => a.concat(`${c[0]}=${valueOf(c[1])}`), [])
    .join('&');
  httpClient.RequestUri = `${url}${connector}${param}`;
  return httpClient.Get();
};
const valueOf = (column) => {
  const raw = model[column];
  if (raw === undefined) return '';
  if (column.startsWith('Date')) {
    const d = new Date(raw.getTime());
    d.setHours(d.getHours() + 9);
    return `${d.getFullYear()}/${d.getMonth() + 1}/${d.getDate()}`;
  }
  return encodeURIComponent(raw);
};

利用コード

• 更新前や行表示の前、画面表示の前での利用を想定^[1]
  • 行表示のときは、参照しているパラメータが一覧に表示されている必要がある
    • 下記の例だと、祝日名を取得するとき date は必須なので DateA を画面に出しておくこと
  • 画面表示の前のときは、パラメータとなるデータ項目に自動ポストバックを有効化しておけば、変更にあわせて動的にデータを書き換えることも可能

try {
  model.Body = WEBSERVICE('https://api.excelapi.org/datetime/holiday', {
    date: 'DateA',
    country: 'ClassA',
  });
  model.DescriptionA = WEBSERVICE(
    'https://api.excelapi.org/post/address-separate?parts=1',
    {
      address: 'ClassA',
    },
  );
} catch (e) {
  context.Log(e.stack);
  context.Log(e.message);
}

具体的な、使い方としてはExcelAPI さんの機能一覧から、各機能を見て

• 「URL」(使用例ではなく URL のほう)セクションにある URL を 1 つめの引数にする
  • 固定値を利用したい場合は、使用例を参考に URL 部分にパラメータの埋め込みを行う(^ の住所分割の例では ?parts=1 を指定)
• 「設定」セクションにある"設定"列をキーに、対応する値をデータベースの項目名にそれぞれ指定したオブジェクトを 2 つ目の引数にする

おわりに

• 脱 Excel しても ExcelAPI は使えそう
• 画面の負荷になるので、サーバスクリプトの多用(特に画面表示に伴う描画)は用量を守ってご利用ください

脚注

1. 今回の内容に限らないが、サーバスクリプトの条件の使い分けについて。行表示/画面表示の前でデータを加工すると、ブラウザでも CSV エクスポートでも API 取得でもどの段階でも加工済みのデータが取得できる。これはデータ保持する必要がなく、かつ動的に書き換えたほうが良いデータ(目標日までの残り日数のように刻々と変わる場合など)での利用に向く。メリットとしてデータメンテをする必要がないことがあるが、デメリットとして画面表示に時間がかかることと、演算結果については検索ができないことがある。他方、更新前はデータ保持されるので、頻繁には更新されず、また同一テーブル内のデータ項目だけに連動して変わるデータに向く。メリットとして、データ保持するので都度の画面表示に影響がなく、演算結果に対する検索が可能となることがあるが、デメリットとして、既にデータ投入がなされているカラムに対してスクリプトを置いても、過去データは更新を実行するまで処理が適用できないこと、が考えられる。