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

このヘルプページは Creator 6 をご利用のユーザー向けです。ご利用中のCreator のバージョンを確認してください。

1. このページの内容

2. 提供状況

カスタム API:

1. すべての Creator プランで作成および管理できますが、呼び出し上限は契約プランによって異なります。
2. 作成および管理できるのはスーパー管理者と管理者のみです。他の種類のユーザーは、設定されたユーザースコープに基づいて呼び出すことができます。

3. 概要

4. Creator におけるカスタム API

カスタム API を作成・管理するためのカスタム API ビルダーにアクセスできるのは、スーパー管理者と管理者のみです。

メモ:

1. API ヒット数は、料金の観点では REST API のヒット数とは別にカウントされます。
2. 現在は、すでに設定済みのDeluge 関数のみをカスタム API として使用できます。つまり、クラウド関数として作成した Java や NodeJS のスクリプトを、カスタム API として呼び出すことはできません。

4。1 Creator におけるカスタム API の機能

1. カスタム API を使用すると、通常は Creator 内でのみ可能な操作を外部から呼び出すことができます。例として、プッシュ通知の送信、AI フォーム項目からの結果取得、その他のデータ関連処理の実行などがあります。
2. カスタム API 内で、Creator 独自のDeluge 関数をそのまま呼び出せるため、Deluge 関数を書き直したり、別のカスタム API を作成したりする必要がありません。
3. 認証メカニズムを実装して、安全なカスタム API を構築できます。これにより、データアクセスを制御・保護し、不正アクセスやデータ漏えいのリスクを軽減できます。
4. 1 回の関数実行で複数のロジック処理をまとめて実行できます。
5. 多数の API コールや外部スクリプトを通じて大規模な処理を実行する場合でも、カスタム API のログを 1 か所でまとめて分析・管理できます。

4。2 Creator でカスタム API はどのように構築されるか

1. カスタム API ビルダー: セキュアで簡単に作成できるインターフェイスで、すぐに利用可能なカスタム APIを作成でき、Creator と外部システム間のデータ連携を実現します。
2. Deluge 関数: 既存のDeluge 関数をカスタム API から呼び出すことができます。

4。3 Creator におけるカスタム API の構成要素

1. 基本情報
2. エンドポイント URL
3. ユーザースコープ
4. Request
5. Function
6. Response

基本情報

カスタム API に名前を付ける際は、その機能を表し、覚えやすく、内容が分かりやすい名前を付けることが重要です。

エンドポイント URL の機能

1.エンドポイント URL を取得する方法

エンドポイント URL は、次の場所からコピーできます。

1. 該当するカスタム API カード
2. 詳細ビュー
   

次の動画では、エンドポイント URL をコピーできる場所を示しています。

2. エンドポイント URL にアクセスできるユーザー

「Request」タブで定義されたユーザースコープによって、カスタム API にアクセスし呼び出せるユーザーが決まります。

メモ: 権限のないユーザーがエンドポイント URL を使ってカスタム API を呼び出そうとした場合、システムレスポンス（Creator のレスポンス）が表示されます。

メモ:

1. カスタム API を呼び出すには、エンドポイント URL をコピーして、必要な外部プラットフォームに貼り付ける必要があります。
   
2. カスタム API のリンク名を編集したり、ユーザースコープや認証方法を変更した場合、エンドポイント URL のプレビューはカスタム APIビルダー内で自動的に更新されます。ただし、すでにエンドポイント URL を設定している箇所は手動で更新する必要があります。エンドポイント URL を更新せずにカスタム API を呼び出した場合は、システムレスポンス（エラー）が返されます。

Request

1. リクエストメソッド
2. 認証方式
3. ユーザー範囲
4. コンテンツタイプ

カスタム API のリクエストメソッド

1. GET: 指定したエンドポイント URL からデータを要求して取得するためのメソッドです。GET リクエストでは、データは通常、URL の末尾に付加されたクエリパラメーターとして送信されます。
2. POST: 指定したエンドポイント URL に処理対象のデータを送信するためのメソッドです。POST リクエストでは、データは通常、JSON やフォームデータなどの形式でリクエスト本文に含めて送信されます。この場合、データは URL には付加されません。
3. PUT: 指定した URL 上の既存リソースを更新または置き換える、あるいは新しいリソースを作成するためのメソッドです。
4. DELETE: 指定した URL 上のサーバーから特定のリソースを削除するためのメソッドです。

認証方式

1.  OAuth2 - 既定では、'Open Authorization' を意味する OAuth により、API コールの認可と認証を行います。Creator アプリケーションが外部リソースへ安全にアクセスできるようにし、ユーザーがログインするたびにユーザー名とパスワードを求める手間を軽減します。このオプションを選択した場合、ユーザー範囲で指定したユーザーのみがカスタム API にアクセスして呼び出すことができます。
   
2. PublicKey - このオプションを選択した場合、誰でもカスタム API にアクセスして呼び出すことができます。

Info: エンドポイント URL には、公開キーをパラメーターとして付加する必要があります。

ユーザー範囲

1. Admin only - スーパー管理者と管理者
2. 選択したユーザー - スーパー管理者、管理者、およびユーザー（このオプションを選択したときに表示される入力項目でメールアドレスを指定）
3. ポータルユーザー - アプリケーションのポータルに追加され、処理タブで選択されたポータルの承認済みポータルユーザー
   
4. すべて - Creator アカウントのユーザー タブにいるすべての有効なユーザー。ポータルユーザーは含まれません。

メモ:

1. カスタム API のユーザー範囲を選択したユーザーからAdmin only、ポータルユーザー、またはすべてに変更すると、これまで追加していたユーザーはすべて削除されます。
   
2. ポータルユーザーをユーザー範囲として選択した場合、カスタム API はウィジェット内からのみ呼び出すことができます。詳細はこちら

コンテンツタイプ

メモ: コンテンツタイプを選択できるのは、POST および PUT メソッドのみです。

1. Application/JSON: このコンテンツタイプを選択すると、API リクエスト内のデータが JSON（JavaScript Object Notation）形式であることを示します。これにより、外部サービスはリクエスト本文内のデータが JSON 形式であり、それに応じて処理する必要があることを認識します。

JSON は、データオブジェクト、配列、キーと値のペアを表現するためによく使用される汎用的なデータ交換形式であり、人間にも機械にも読みやすい形式です。クライアントとサーバー間で構造化データを送受信する際によく使用されるため、API 通信に最適な形式です。

1. Multipart/form-data: このコンテンツタイプは、ファイルなどのバイナリデータやテキストデータを外部サービスに送信する API リクエストで使用されます。multipart/form-data リクエストでは、データは複数のパートに分割され、各パートは独自のコンテンツタイプとヘッダーを持ちます。これにより、データ本体だけでなく、ファイル名、項目名、各パートのコンテンツタイプなどの追加情報も含めることができます。パート同士を区切るためにバウンダリ文字列が使用され、この文字列は各パートの開始位置と終了位置を示すためにリクエストヘッダーで指定されます。

Multipart/form-data は、ユーザーがファイルをアップロードできる API エンドポイントを作成する場合や、ファイルアップロード項目を含むフォームを扱う場合によく使用されます。ファイル入力項目を含むフォームをユーザーが送信すると、そのフォームに紐づくカスタム API が呼び出され、外部サーバーにデータを送信するための 'multipart/form-data' リクエストが生成されます。

メモ:

1. Multipart/form-data では JSON のような入れ子構造のデータは扱えず、個々の「キーと値」のペアのみを含みます。
2. JSON と異なり、1 つのキーに対して複数の値を持つことができます。

1. キーと値: このタイプでは、API エンドポイントに入力パラメーターをキーと値のペアとして渡します。少数の、名前付きパラメーターを API リクエストで渡す必要がある場合に適しています。
   

1. Entire JSON: このタイプでは、必要なキーと値のペアをすべて含む、完全で構造化された JSON オブジェクト全体を 1 つの引数として渡します。Webhook コールを処理する場合などにこの方法を使用できます。
   

サンプルリクエスト:

1. {
2. 'ユーザー':{
3. 'id':12345,
4. '名前':'Alisa',
5. 'メール':'alisa@zylker.com',
6. '年齢':28,
7. '住所':{
8. '町名・番地':'123 Main St',
9. '市区町村':'Anytown',
10. '国':'Zylkerland'
11. },
12. '注文':[
13. {
14. 'order_id':1001,
15. 'total_amount':75。50,
16. 'ステータス':'納品済み'
17. },
18. {
19. 'order_id':1002,
20. 'total_amount':102。20,
21. 'ステータス':'保留中'
22. }
23. ]
24. },
25. 'ステータス':'完了',
26. 'メッセージ':'ユーザー data retrieved successfully'
27. }

上記の例では:

1. JSONレスポンスには、さまざまな入れ子構造の要素が含まれています。
2. 'ユーザー' には、ID、名前、メール、年齢、住所、注文リストなど、ユーザーに関する情報が含まれています。
3. '住所' はユーザー詳細内の入れ子オブジェクトで、住所に関する情報を含みます。
4. '注文' は、ユーザーが行った複数の注文を表すオブジェクトを含む配列で、各オブジェクトには注文 ID、合計金額、ステータスなどの属性があります。
5. 'ステータス' と 'メッセージ' は、API リクエスト／レスポンス全体のステータスに関する追加情報を提供します。
   

このカスタム API で Entire JSON を選択する場合は、文字列データ型の引数を 1 つだけ指定し、その中で各キーが特定の値に関連付けられるようにしてください。

レスポンス

1. 標準レスポンス: このレスポンスでは、標準のステータスコードが返されます。このオプションを選択すると、下部にサンプルレスポンスが表示されます。
   
   
2. カスタムレスポンス: このレスポンスでは、要件に応じてカスタムのステータスコードと、それに対応するレスポンスコードを定義・指定できます。
   
   

メモ:

1. 各ステータスコードにつき、最大50 個のレスポンスコードまで指定できます。
2. カスタムレスポンスコードは最大 4 桁まで指定できます。
3. カスタムコードを指定する場合、呼び出されるDeluge 関数の返却型はMapである必要があります。
4. 指定したレスポンスコードと、それに対応する説明メッセージ
   を Deluge 関数内でマッピングする必要があります。

Function

処理タブでは、カスタム API が呼び出されたときに実行されるDeluge関数を含む Creator アプリケーションと名前空間を選択できます。

1. アプリケーションは、現在属している環境（Development または Stage）とともに一覧表示されます。
2. Deluge 関数を作成する際は、適切な名前空間と関数名を指定することを推奨します。これにより、カスタム API の処理を定義しやすくなります。
   
3. Deluge 関数に機密性の高い処理を含める場合や、ユーザー スコープを通じてカスタム API の呼び出し権限を付与する場合は、十分に注意することを推奨します。

概要

カスタム API を作成して保存前にページを終了した場合、そのカスタム API は下書きとして保存されます。

カスタム API を正常に作成したあと、概要タブで、そのカスタム API の基本情報、使用されているアプリケーション、および作成・更新の詳細を確認できます。

API ログ

1. API ログには、初期設定で過去 30 日間のログが表示され、最大で過去 60 日間までさかのぼって表示できます。
   
2. API ヒットを表示できるのはスーパー管理者と管理者のみです。一般ユーザーは API ヒットを表示できません。

カスタム API を呼び出すためのスコープ

Method	Scope
GET、POST、PUT、DELETE	Zohocreator.customapi.execute

5. 動作イメージ

1. 運行開始前に、運行エリア内にいる事務・非教職員、学生、非教職員の送迎先住所を取得する。
2. 各運行終了時に、学生の出欠情報と平均運行速度を送信する。

1. 3 つのデータ取得 APIを使用して、3 つの個別レポートから住所を取得します。
2. 2つの データ追加 APIを使用して、運行に関する詳細を追加し、その日の出欠情報をデータとして登録します。

6. ユースケース

1. 病院管理: たとえば、クリニックを運営しており、Creator を使ってHospital Managementアプリケーションを作成しているとします。患者が装着しているセンサー付き医療機器から重要な情報を取得し、医師がすぐに通知を受けてバイタルを監視し、必要に応じて医療支援を提供できるようにしたいとします。この場合、心拍数、血圧、酸素濃度などの各種バイタルを考慮し、異常値が検出されたときに呼び出されるカスタム API を設定できます。デバイスは API リクエストを通じて、担当医師の空き状況に基づき、該当する医師にモバイル通知としてこれらの詳細を送信します。担当医師には、Creator 上でポップアップフォームを表示し（軽度の緊急時を想定）、治療担当スタッフに対する医療アドバイスを送信できるようにできます。また、医師はすぐに診察が必要かどうかを選択し、最短の予約枠を確保できます。患者は、API レスポンスを通じて、処方された医療アドバイスと（該当する場合は）予約の詳細を受け取ります。このデータは、Appointment 予約フォームおよびPatient 詳細フォームにも追加できます。
2. 承認管理: たとえば、Creator を使ってプロジェクト Managementアプリケーションを作成しているとします。従業員は外部サービス上で提案書ドキュメントを作成し、それをあなた（管理者）が承認する必要があります。さらに、ドキュメントが承認されるたびに Creator アプリケーションにデータを追加し、却下されたドキュメントのデータも管理したいとします。この場合、外部サービスから承認用にドキュメントが送信されたときに呼び出されるカスタム API を作成できます。これにより、Creator 内の承認ワークフローがトリガーされ、ドキュメントの承認プロセスが開始され、ドキュメントのステータスが「承認済み」に変更されます。プロジェクト 詳細レポートとQuote 詳細レポートに、それぞれデータが追加されます。ドキュメントが却下された場合は、ドキュメントのステータスが「却下済み」に更新され、その後、プロジェクト 詳細レポートとドキュメント フィードバックレポートにデータが追加されます。

7. カスタム API 作成のナビゲーションガイド

8. 注意点

1. カスタム API のリンク名には、!@#$%^&*.> などの特殊文字を含めることはできません。
   
2. カスタムレスポンスのステータスコードは、100 ～ 599の範囲で指定できます。
3. カスタムレスポンスのレスポンスコードは1 ～ 9999の範囲で指定する必要があり、!@#$%^&*.> などの特殊文字を含めることはできません。
4. カスタム API ビルダーを保存せずに閉じた場合でも、変更内容は下書きとして保存され、Microservices > カスタム API > 対象のカスタム API カードからいつでも編集を再開できます。
5. 無効な API を呼び出した場合、空のレスポンスが返されます。つまり、無効な API を呼び出すと API ログには記録されますが、API ヒットとしてはカウントされません。
6. カスタム API で使用中の関数を削除する前に、その関数に関連付けられているカスタム API を削除しておく必要があります。

9. 関連トピック

1. カスタム API の作成と管理
   
2. カスタム API ステータスコード
3. Creator の REST API