ウィジェット用JS API

ウィジェット用JS API

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

1. ウィジェット内での JS API

Zoho Creator では、アプリケーションのウィジェットを、アプリケーションのページコンポーネントに挿入した状態で、CRUD 操作を実行できる JS API タスクを提供しています。これらを使用すると、同じ Creator アカウント内の他のアプリケーションのデータを追加・操作することもできます。言い換えると、これらのタスクは Creator のREST APIのラッパーです。アプリケーションでタスクを実行するための API 呼び出しの完了可否は、対象アプリケーションのウィジェットにアクセスするユーザーに付与されている権限に依存します。
利用可能な JS API のバージョンは次の 2 つです:
V1 - REST API V2 をベースにしています
V2 - REST API V2.1 をベースにしています（推奨）

例 - たとえば、独自にカスタマイズしたフィードバックマトリックス形式のフォームを作成したいとします。これは、フォームをウィジェットとして作成し、ページに挿入することで実現できます。このフォームはウィジェット内に配置されるため、アプリケーションデータを操作するには JS API タスクを実行する必要があります。

2. 利用ケース

同一アプリケーション内でのデータの追加・更新 - たとえば、プロジェクト管理アプリケーションにタイマーウィジェットを挿入したとします。従業員がプロジェクトの作業を開始するとき、ウィジェット内の開始ボタンをクリックします。これにより、プロジェクトタイムラインフォームにレコードが追加されます。従業員がプロジェクトを完了し、プロジェクトを完了ボタンをクリックすると、同じレコードが終了時刻で更新されます。これは、それぞれ レコードの追加およびレコードの更新JS API タスクを使用して実現されます。

3. JS API の設定

ウィジェット内で JS API タスクを記述するには、次の設定を行う必要があります。
手順 1 : ウィジェットパッケージの HTML ファイルで行う操作
以下の CDN URL を、ウィジェットの HTML ファイルの script タグにリンクして読み込みます。この HTML ファイルは、ウィジェットパッケージを作成すると自動的に作成されます。
  1. <script src='CDN URL'></script>
Info
V1 の場合:
V2 の場合:
Notes
メモ:
  1. ウィジェット内で実行できるタスクは、指定したバージョンに対応するものに限定されます。たとえば、ウィジェット内でJS API V2 のレコード取得タスクを実行したい場合、ウィジェットの HTML ファイルに V2 用の CDN URL を指定している場合にのみ、レコードが取得されます。

手順 2 : ウィジェットパッケージの JS ファイルで行う操作
ウィジェットパッケージ内に JS ファイルを作成し、インタラクティブな要素を含めます。同じファイル内で、JS API タスクのロジックも記述します。あるいは、JavaScript コードをウィジェットパッケージの HTML ファイル内（手順 1）に直接記述することもできます。
Notes
JS API V1 の要件:
V1 の場合、JS API タスクのロジックを記述する前に、CDN URL に含まれる SDK を初期化する必要があります。ウィジェットパッケージの JS ファイルで、次のメソッドを使用してください。
  1. Zoho.CREATOR.init()
  2. .then(function(data) {
  3. //Code goes here
  4. });

4. JS API タスク

ウィジェット内で実行できる JS API V2 タスクは次のとおりです:
1. データ API
  2. ID によるレコード取得
  3. レコードの取得
  4. レコード件数の取得
  5. ID によるレコード更新
  6. レコードの更新
  7. ID によるレコード削除
  8. レコードの削除
 2. 公開 API
  1. レコードの追加
  2. ID によるレコード取得
  3. レコードの取得 
 3. ファイル API
  1. ファイルのアップロード
  2. ファイルの読み取り
4. メタ API
  1. フィールドの取得
  2. フォームの取得
  3. レポートの取得
  4. ページの取得
  5. セクションの取得
  6. アプリケーションの取得
  7. ワークスペース別アプリケーションの取得
5. ユーティリティ API
  1. 画像データの設定
  2. 親 URL への遷移
  3. 初期化パラメーターの取得
  4. クエリパラメーターの取得
  5. ウィジェットパラメーターの取得
Info
これらのタスクのうち、V1 でサポートされるのは一部のみです。V1 で実行可能なタスクの詳細については、JS API V1 の概要を参照してください。

5. 注意点

バージョンごとの制限
  1. ウィジェット内で実行できるタスクは、そのとき指定しているバージョンに対応するものに限定されます。たとえば、ウィジェット内でJS API v2 のレコード取得タスクを実行したい場合、ウィジェットの HTML ファイルに v2 用の CDN URL を指定している場合にのみ、レコードが取得されます。
  2. 現在の JS API バージョンを変更する必要がある場合は、次の変更を行う必要があります。
    1. ウィジェットパッケージの HTML ファイル内の CDN URL を、必要なバージョンのものに変更する
    2. SDK の初期化は JS API v1 のみ必須です。必要なバージョンに応じて、ウィジェットパッケージの JS ファイル内で初期化メソッドを追加または削除します。
    3. ウィジェットパッケージの JS ファイル内で、JS API タスクの構文および設定パラメーターを、必要なバージョンの仕様に合わせて更新します。
その後、ウィジェットファイルを再アップロードする必要があります。CDN URL を更新すると、それまで使用していたバージョンでのみ動作していたタスクは、以降は動作しなくなる点に注意してください。
一般
  1. ウィジェットのファイル内にある JS スクリプトを変更した場合、ウィジェットを期待どおりに動作させるには、変更後のファイルを再アップロードする必要があります。
  2. タスクを正常に実行するには、設定内でそのタスクに必須のパラメーターを必ず指定してください。
  3. Creator アカウントを持たないユーザーがアクセスできる公開ページでは、公開 API タスクのみが動作します。