FileMaker 18 Data API ガイド
FileMaker Data API について
概要
FileMaker® Data API は、共有データベースのデータに Web サービスからアクセスできるようにするアプリケーションプログラミングインターフェース (API) です。この API は REST (Representational State Transfer) アーキテクチャを使用しているため、FileMaker Data API は REST API です。
Web サービスまたはアプリケーションによる FileMaker Data API の呼び出しによって認証トークンを取得して共有データベースにアクセスします。以降の呼び出しでそのトークンを使用してレコードの作成、レコードの更新、レコードの削除、検索の実行を行います。
FileMaker Data API は、特定のプログラミング言語形式に依存しないことから REST API で一般的に使用されているテキスト形式 JSON (JavaScript Object Notation) でデータを返します。
このガイドでは、次の経験があることを想定しています:
- FileMaker Pro Advanced を使用したデータベースの作成。データベースの設計の基礎、ならびにフィールド、リレーションシップ、レイアウト、ポータル、およびオブジェクトの概念について理解している必要があります。FileMaker Pro Advanced ヘルプを参照してください。
- FileMaker Server または FileMaker Cloud 製品を使用したデータベースの共有。ホストの設定方法、共有データベースへのアクセスを有効にする方法、および FileMaker Server Admin Console を使用して共有データベースを監視する方法について理解している必要があります。
- 「FileMaker Cloud」は FileMaker Pro Advanced、FileMaker Go、および FileMaker WebDirect を使用するカスタム App をクラウド上で使用するためのサービスです。FileMaker Cloud では FileMaker ID と統合されたサインオンシステムを使用してユーザを認証します。FileMaker Cloud は FileMaker, Inc. から直接提供されます。
- 「FileMaker Cloud for AWS」は FileMaker Pro Advanced、FileMaker Go、および FileMaker WebDirect を使用するカスタム App をクラウド上で使用するためのサービスです。FileMaker Cloud for AWS は AWS (Amazon Web Services) クラウド上で実行され、AWS Marketplace から提供されます。
- 「FileMaker Cloud 製品」は FileMaker Cloud および FileMaker Cloud for AWS の両方を意味します。
- POST、GET、PATCH、および DELETE メソッドと JSON 形式のデータを呼び出すサーバーサイドアプリケーションまたは Web サービスでの REST API の使用。任意のプログラミング言語またはプログラミングツールを使用できる必要があります。
このガイドでは「Admin Console」は特定の製品について説明する場合以外、FileMaker Server、FileMaker Cloud for AWS、および FileMaker Cloud の Admin Console を意味します。「FileMaker Cloud Admin Console」は特定の製品について説明する場合以外、両方の FileMaker Cloud 製品の Admin Console を意味します。
FileMaker Data API を使用するには次の手順に従います:
- FileMaker Pro Advanced を使用して FileMaker Data API アクセス用のデータベースを準備します。データベースを新規作成するか、または既存のデータベースを準備します。「FileMaker Data API アクセス用のデータベースの準備」を参照してください。
- 共有データベース内のレコードを検索、作成、編集、複製、削除する FileMaker Data API メソッドを呼び出すコードを作成します。「FileMaker Data API 呼び出しの作成」を参照してください。
- ソリューションを共有して FileMaker Data API アクセスを有効にします。「FileMaker Data API ソリューションの共有」を参照してください。
- FileMaker Data API アクセスが正しく動作するかをテストします。「FileMaker Data API ソリューションのテスト」を参照してください。
- Admin Console を使用して共有ソリューションを監視します。「FileMaker Data API ソリューションの監視」を参照してください。
FileMaker Data API 呼び出しの処理の流れ
REST API クライアント
1
6
Web サーバー
2
5
FileMaker Data API エンジン
3
4
データベースサーバー
-
REST API クライアントが HTTPS ポート (ポート 443) を使用して Web サーバーに FileMaker Data API 呼び出し (HTTPS リクエスト) を送信します。FileMaker Pro Advanced がインストールまたは実行されている必要はありません。
- Web サーバーが、FileMaker Web サーバーモジュールを使用してリクエストを FileMaker Data API エンジンにルーティングします。
- FileMaker Data API エンジンが、HTTPS リクエスト (URL および JSON データ) をデータベースサーバーコンポーネントが解釈できる形式に変換し、データベースサーバーで共有されているデータベースのデータを要求します。
- データベースサーバーが要求された FileMaker データを FileMaker Data API エンジンに返します。
- FileMaker Data API エンジンが FileMaker データを HTTPS 応答 (URL および JSON データ) に変換して Web サーバーにデータを渡すことで呼び出しに応答します。
- Web サーバーが要求元の REST API クライアントに HTTPS 応答を送信します。
FileMaker Data API エンジンでは、ポート 3000 および 8989 が利用可能な状態である必要があります。
データベースサーバーでは、ポート 5003 が利用可能な状態である必要があります。
その他の Web 公開方法
REST API の使用経験がない場合は、次の方法で FileMaker データをインターネット上で公開することを検討してください。
FileMaker WebDirect™: アクセス権が付与されている場合、Web ユーザは共有データベースに接続してレコードを表示、編集、ソート、または検索できます。互換性のある Web ブラウザソフトウェアとインターネットまたはイントラネットへのアクセスがあれば、追加のソフトウェアをインストールする必要はありません。ユーザインターフェースは、FileMaker Pro Advanced アプリケーションに似ています。Web ユーザが操作する Web ページおよびフォームは、FileMaker Pro Advanced データベースで定義されたレイアウトおよび表示形式によって変わります。
FileMaker WebDirect ガイドを参照してください。
静的公開: データに変更がほとんどない場合、またはユーザによるデータベースへのライブ接続を要求しない場合は静的公開を使用することができます。静的公開では、FileMaker Pro Advanced データをエクスポートして Web ページを作成し、HTML でさらにカスタマイズできます。データベースの情報が変更されても Web ページは変更されません。ユーザはデータベース自体には接続しません。
FileMaker Pro Advanced ヘルプの「静的 Web ページでデータを公開する」を参照してください。
カスタム Web 公開: FileMaker データベースをカスタム Web サイトに統合するには、FileMaker Server によって提供されるカスタム Web 公開テクノロジーを使用します。
『FileMaker Server カスタム Web 公開ガイド』を参照してください。
FileMaker Data API アクセス用のデータベースの準備
アクセスするデータの決定
FileMaker Data API で使用する FileMaker Pro Advanced データベースを新規作成するか、または既存のデータベースを使用することができます。データベースを新規作成する場合は、FileMaker Data API ソリューションに合わせてレイアウトおよびフィールドをデザインできます。既存のデータベースを使用する場合は、FileMaker Data API ソリューション用に特化したレイアウトを作成することを検討してください。
レコードデータにアクセスする場合は、FileMaker Data API 呼び出しでレイアウトを指定する必要があります。FileMaker Data API は、指定するレイアウトに定義されているデフォルトの表示形式を使用します。
レイアウトのデフォルトの表示形式としてフォーム形式が定義されているレイアウトを指定してください。デフォルトの表示形式として表形式が定義されているレイアウトを使用する場合、FileMaker Data API は最初の関連レコード以外からはデータを取得できません。
FileMaker Data API ソリューションの保護
FileMaker Data API では、パスワードで保護されたアカウントを使用してデータベースセッションにログインするのに REST API コードが必要です。REST API アクセスに使用するデータベースアカウントにパスワードを割り当てるか、またはこれらのアカウントに対して OAuth サービスプロバイダを使用してください。
メモ
- FileMaker Data API ソリューションのアカウント名とパスワードを定義する際は、表示可能な ASCII 文字 (a から z、A から Z、0 から 9 など) を使用してください。アカウント名とパスワードのセキュリティを高めるには「!」や「%」などの記号を含めます。ただし、コロンは含めないでください。FileMaker Pro Advanced ヘルプを参照してください。
- FileMaker Cloud で共有されているデータベースの場合、FileMaker ID アカウントを使用する必要があります。プロダクトドキュメンテーションセンターで FileMaker Cloud のマニュアルを参照してください。
FileMaker Data API アクセスの有効化
FileMaker Data API を使用してアクセスする各データベースで fmrest 拡張アクセス権 [FileMaker Data API でのアクセス] を有効にする必要があります。fmrest 拡張アクセス権を有効にしない場合、データベースが共有されていても REST API アプリケーションは FileMaker Data API を使用してデータベースにアクセスできません。
メモ:セキュリティ上の理由から、FileMaker Data API を使用したアクセスを許可するアカウントのアクセス権セットでのみ fmrest 拡張アクセス権を有効にします。
FileMaker Pro Advanced ヘルプの「アクセス権セットの拡張アクセス権の編集」を参照してください。
FileMaker Data API ソリューションの設計
FileMaker Data API の機能
FileMaker Data API は、共有データベースのデータにアクセスするための REST API を提供します。FileMaker Data API を使用すると、コードで次の操作が可能になります:
- 製品情報および共有データベースの名前などのホストに関する情報の取得。「メタデータの取得」を参照してください。
- スクリプト名、レイアウト名、またはレイアウトメタデータ (フィールド名、値一覧名、および値一覧の内容) などの共有データベースに関する情報の取得。「メタデータの取得」を参照してください。
- 共有データベースへのログインまたはログアウト。「データベースへの接続の確立または接続解除」を参照してください。
- レコードの作成、編集、複製、削除、取得、またはレコードの範囲の取得。「レコードの操作」を参照してください。
- 検索の実行。「検索の実行」を参照してください。
- グローバルフィールドの値の設定。「グローバルフィールドの値の設定」を参照してください。
- FileMaker スクリプトの実行。「FileMaker スクリプトおよび FileMaker Data API」を参照してください。
- オブジェクトフィールドへのデータのアップロード。「オブジェクトデータのアップロード」を参照してください。
- 外部 FileMaker テーブルのデータへのアクセス。「外部データソースへのログイン」を参照してください。
- レコードまたはレコードの範囲の取得時における応答データへの別のレイアウトの使用。「単一のレコードの取得」、「レコードの範囲の取得」、および「検索の実行」を参照してください。
FileMaker Data API では、次の操作はサポートされません:
- 外部 ODBC データソースのデータへのアクセス
- FileMaker プラグイン
- ユーザインタラクションによるスクリプトトリガのアクティブ化。FileMaker Data API ソリューションでは、FileMaker スクリプトを実行する方法でのみスクリプトトリガをアクティブにすることができます。
- サーバーマシンのファイルシステムへのアクセス。たとえば、FileMaker Data API では、FileMaker Pro Advanced の Get (テンポラリパス) 関数はサポートされません。この関数を FileMaker Data API とともに使用した場合、空の文字列が返されます。オブジェクトフィールドにファイルを保存することはできますが、サーバーのファイルシステムにはアクセスできません。
FileMaker Data API は FileMaker Pro Advanced に表示されるフィールドデータではなく、データベースに保存されているフィールドデータを返します。
FileMaker Data API Reference
FileMaker Data API Reference には、FileMaker Data API でサポートされるすべての呼び出しに関する詳細情報が含まれています。
メモ: FileMaker Data API Reference を表示するには Admin Console で FileMaker Data API アクセスが有効に設定されていることを確認します。プロダクトドキュメンテーションセンターを参照してください。
- FileMaker Cloud ホスト上でリファレンスを表示するには、ブラウザを開いて次の URL を入力します。
https://<ホスト>/fmi/data/apidoc/
<ホスト> は FileMaker Cloud ホストの IP アドレスまたはホスト名です。 - FileMaker Server のマスタマシン上でリファレンスを表示するには、ブラウザを開いて次の URL を入力します。
https://localhost/fmi/data/apidoc/ - FileMaker Server のリモートマシン上でリファレンスを表示するには、ブラウザを開いて次の URL を入力します。
https://<ホスト>/fmi/data/apidoc/
<ホスト> は FileMaker Server が実行されているマスタマシンの IP アドレスまたはホスト名です。 Windows サーバー上にインストールされた FileMaker Server の場合、リファレンスファイルは次のフォルダ内にあります。
[ドライブ]:¥Program Files¥FileMaker¥FileMaker Server¥Documentation¥Data API Documentation
[ドライブ]は FileMaker Server 展開が存在するドライブです。Windows 上のデフォルト以外の場所にインストールした場合、次のようにデフォルトのインストールパスの先頭部分がインストール場所に置き換わります。
[ドライブ]:[インストール場所]¥FileMaker¥FileMaker Server¥Documentation¥Data API Documentation- macOS サーバー上にインストールされた FileMaker Server の場合、リファレンスファイルは次のフォルダ内にあります。
/ライブラリ/FileMaker Server/Documentation/Data API Documentation
メモ
- リファレンスファイルでは先頭にコロン (:) の付いたキーワードを使用して URL 内の変数を示しています。例:
:database - このガイドでは斜体フォントを使用して URL 内の変数を示しています。例:
database-name
URL およびデータ形式に関する注意点
- FileMaker Data API の URI の最大長は、オペレーティングシステム、Web サーバー、および Web ブラウザがにより異なる場合があります。クロスプラットフォームで最適に使用するには、URI の長さを 2000 文字までにします。
- URL または URL の一部で大文字と小文字が区別されない場合もありますが、通常は大文字と小文字が区別されると考えてください。たとえば、データベースセッションにログインするために小文字のデータベース名を使用する場合、同じセッショントークンが承認されるすべての URL にも小文字のデータベース名を使用します。小文字のデータベース名を使用しない場合、トークンが無効であるというエラーメッセージが表示されることがあります。
- URL 内の文字列は HTTP リクエストの標準である URL エンコーディングを使用する必要があります。これはパーセントエンコーディングとも呼ばれます。たとえば、スラッシュ文字を含むレイアウト名を指定するには、スラッシュ文字をエンコード値「%2F」として指定する必要があります。
- リクエストのボディで引数に指定する文字列のデータ値は UTF-8 エンコードを使用する必要があります。
- 通常、FileMaker Data API では、数字のデータ値を倍精度浮動小数点形式 (binary64) のデータとして処理します。使用するプログラミング言語で倍精度浮動小数点形式に対応するデータ形式を使用してください。(数字データ値はクォーテーションマークで囲まず、URL エンコーディングを使用しません。)
- 数字、日付、時刻、およびタイムスタンプフィールドのデータ値は、FileMaker Pro Advanced で定められている制限に従ってください。FileMaker Pro Advanced ヘルプを参照してください。
- 指定するフィールドおよびポータルは、指定するレイアウト上に存在する必要があります。
- 関連フィールドを指定するには、
portalData構文を使用する必要があります。メモ: 以前にリリースされた「
テーブル名::関連フィールド (繰り返し数).レコード ID」という構文も引き続きサポートされますが、portalData構文が推奨されます。 - 応答のボディでは、FileMaker Data API は現在のテーブルのフィールドのフィールド名および関連テーブルのフィールドの完全修飾名のみを返します。ポータルフィールドの場合、インスペクタでポータルの名前が指定されていると、完全修飾名にポータルの名前が使用されます。そうでない場合、完全修飾名にはテーブルオカレンス名が使用されます。
- オブジェクトフィールドデータの場合、FileMaker Data API はオブジェクトデータのオブジェクトへのパス参照を含む URL を返します。
FileMaker スクリプトおよび FileMaker Data API
FileMaker スクリプトは、繰り返し実行する操作や面倒な操作を自動化するために定義する 1 つまたは複数の命令 (スクリプトステップ) です。FileMaker Data API とともに FileMaker スクリプトを使用すると、Web サービスでより多くのタスクや一連のタスクを実行できるようになります。「FileMaker スクリプトの実行」を参照してください。
FileMaker Data API がサポートするスクリプトステップを表示するには、FileMaker Pro Advanced スクリプトワークスペースで互換性ボタンをクリックして [FileMaker Data API] を選択します。グレー表示されていないスクリプトステップが FileMaker Data API でサポートされています。一部のスクリプトステップでは FileMaker Data API で異なる動作、またはサポートされない場合があります。FileMaker Pro Advanced ヘルプを参照してください。
FileMaker Data API により実行されるスクリプトは、ファイルが同じホストで共有されている場合以外は他の FileMaker ファイルのスクリプトを実行できません。他の FileMaker ファイルでは fmrest 拡張アクセス権が有効になっている必要があります。
FileMaker Pro Advanced では、スクリプトとユーザの操作 (ユーザによるフィールドのクリックなど) の両方でスクリプトトリガをアクティブにすることができます。ただし、FileMaker Data API ソリューションでは、スクリプトトリガをアクティブにすることができるのはスクリプトのみです。スクリプトトリガの詳細については、FileMaker Pro Advanced ヘルプを参照してください。
メモ
- スクリプトが返す可能性のあるデータ量やレコード数を考慮して、スクリプトを適切に定義してください。FileMaker Pro Advanced では、スクリプトがテーブルまたは現在の対象レコードのすべてのレコードを返す場合があります。しかし、スクリプトがテーブルのすべてのレコードを返すと、Web サービスでこれらのレコードが処理されるためにメモリが不足する場合があります。
- アカウントとアクセス権を使用して、Web サービスが実行可能なスクリプトのセットを制限します。Web 互換のスクリプトステップのみがスクリプトに含まれることを確認し、Web サービスから使用する必要があるスクリプトのみを利用できるようにします。
- アクセス権によって制御されたステップの組み合わせを実行するスクリプトの影響を考慮します。たとえば、レコードを削除するステップがスクリプトに含まれていて、レコードの削除を許可するアカウントでログインしていない Web サービスの場合、このスクリプトでは、レコードを削除するスクリプトステップは実行されません。ただし、スクリプトは引き続き実行される場合があり、予期しない結果になる可能性があります。
- スクリプトワークスペースで、完全アクセス権をスクリプトに付与して、個人ユーザにアクセスを付与していないタスクの実行を許可します。たとえば、アカウントとアクセス権を使用してユーザがレコードを削除できないようにしつつ、スクリプト内に定義された条件下で特定のレコードを削除するスクリプトの実行を許可することができます。
- FileMaker Data API エンドポイントではデータ変更が即座に確定するようになっていますが、スクリプトではレコードが未確定のままになる場合があります。たとえば、1 つのセッションでレコードを編集して確定はしないスクリプトを実行することができますが、次のセッションで同じレコードを編集しようとするとエラーになります。または単一のセッションの中であれば、1 つのスクリプトでレコードを編集して新規ウインドウを作成してから 2 番目のスクリプトを呼び出して同じレコードの編集をすることができます。必ずスクリプトの結果を検証してスクリプトエラーがないかどうかチェックしてください。
- データをサーバーに保存するまではデータの変更ができないため、データを変更するスクリプトには [レコード/検索条件確定] スクリプトステップを含める必要があります。これには、[切り取り]、[コピー]、[貼り付け] などのスクリプトステップが含まれます。単一ステップの処理の多くは、[レコード/検索条件確定] ステップを含むスクリプトに変換する必要があります。Web サービスから実行されるスクリプトを設計する際は、スクリプトの最後に [レコード/検索条件確定] ステップを含めて、すべての変更が保存されるようにします。
- Web ユーザが実行する可能性のある各スクリプトを開いて、FileMaker Data API ソリューションとしてデータベースを共有するときにスクリプトが適切に実行されることを確認します。上記で説明するように、FileMaker Data API でサポートされているスクリプトステップのみがスクリプトで使用されていることを確認します。
FileMaker Data API 呼び出しの作成
REST API 呼び出しのコンポーネント
FileMaker Data API 呼び出しは次のコンポーネントで構成されます。
| コンポーネント | 説明 |
|---|---|
HTTP メソッド (HTTP 動詞) |
FileMaker Data API は次の HTTP メソッドを使用します:
|
HTTP ヘッダ |
FileMaker Data API は次のヘッダを使用します:
|
| 呼び出し URL | FileMaker Data API の URL はすべて次のいずれかの文字列から始まります:
|
| JSON 形式の引数データ | データベースセッションからのログアウト、メタデータの取得、レコードの削除、レコードの複製、単一のレコードの取得、レコードの範囲の取得、またはスクリプトの実行では必要ありません。 |
データベースへの接続の確立または接続解除
FileMaker Data API では、アクセストークンを使用してデータベースへの接続を定義します。以降はその共有データベースに対するすべての呼び出しのヘッダでそのアクセストークンを使用する必要があります。アクセストークンは、データベースセッションからログアウトするか、またはそのトークンを指定した最後の呼び出しから 15 分経過するまで有効です。(トークンが有効な間は、そのトークンを指定して呼び出しを行うたびにセッションタイムアウトカウンタがゼロにリセットされます。)
データベースセッションへのログイン
共有データベースにログインするには、HTTP POST メソッドを使用して共有データベースの名前を sessions API エンドポイントで指定します。アカウント名とパスワードはヘッダの Authorization 文字列で指定されます。アカウント名とパスワードが認証されると、コードはデータベースへの接続を定義するアクセストークンを受け取ります。この接続は「データベースセッション」と呼ばれます。
| HTTP メソッド | POST |
|---|---|
| URL | /fmi/data/version/databases/database-name/sessions
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ | Content-Type: application/json Authorization: 共有データベースにログインするために使用するアカウント名とパスワードを表す Base64 エンコード文字列。この Base64 エンコード文字列は標準の HTTP 基本認証スキーマに従う必要があります。(アカウント名とパスワードをコロンで区切ります。) |
| 引数 |
空の中カッコ。例:
オプションで |
| 応答 | アクセストークン、アクセストークンを含む応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 応答で X-FM-Data-Access-Token ヘッダが返されます。これは、以降の API 呼び出しで使用するセッショントークンです。 例: ヘッダ:
"X-FM-Data-Access-Token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110",
{
ボディ:
"messages": [
{
"message": "OK",
"code": "0"
}
],
"response": {
"token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110"
},
"HTTPMessage": "OK",
"HTTPCode": 200
}
「エラー応答」を参照してください。 |
外部データソースへのログイン
共有データベースで外部データソースにログインする必要がある場合、共有データベースの名前を URL で指定します。共有データベースのアカウント名とパスワードはヘッダの Authorization 文字列で指定します。外部データソースのデータベース名、アカウント名、およびパスワードは JSON 配列として fmDataSource 引数で指定します。
| HTTP メソッド | POST |
|---|---|
| URL | /fmi/data/version/databases/database-name/sessions
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ | Content-Type: application/json Authorization: 共有データベースにログインするために使用するアカウント名とパスワードを表す Base64 エンコード文字列。この Base64 エンコード文字列は標準の HTTP 基本認証スキーマに従う必要があります。 |
| 引数 | 外部データソースにログインするために使用するデータベース名、アカウント名、およびパスワードを指定する JSON 配列を持つ 例: { "fmDataSource":
[ { "database":"contacts", "username":"admin", "password":"admin" } ]
}
OAuth アカウントを使用して外部データソースにログインする場合、X-FMS-Request-ID ヘッダの値 ( { "fmDataSource":
[ { "database":"contacts", "oAuthRequestId": "E65B98BB17429CO643B31119F", "oAuthIdentifier": "B164A3459A776E5177445DR223"} ]
}
|
| 応答 | アクセストークン、空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 応答で X-FM-Data-Access-Token ヘッダが返されます。これは、以降の API 呼び出しで使用するセッショントークンです。 例: X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メモ
- FileMaker データベースはサポートされている唯一の外部データソースです。データベース名は、.fmp12 ファイル拡張子を付けずに指定してください。
fmDataSource引数で指定されたファイルは、外部データソースを必要とするレイアウトに対してスクリプトが実行されたとき、またはコンテキストが変更されたときなどに必要に応じて開かれます。結果として、ファイルを開くことを試行したときに外部データソースへのログインによるエラーが発生しますが、データベースセッションにログインしたときには発生しません。
OAuth アイデンティティプロバイダを使用したデータベースセッションへのログイン
OAuth アイデンティティプロバイダを使用して共有データベースにログインするには、HTTP POST メソッドを使用してデータベースを sessions API エンドポイントで指定します。ヘッダの X-FM-Data-OAuth-Request-Id 文字列および X-FM-Data-OAuth-Identifier 文字列を使用して共有データベースへのアクセスを認証します。認証されると、コードはデータベースへの接続を定義するアクセストークンを受け取ります。この接続は「データベースセッション」と呼ばれます。
| HTTP メソッド | POST |
|---|---|
| URL | /fmi/data/version/databases/database-name/sessions
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ | Content-Type: application/json X-FM-Data-OAuth-Request-Id: リクエスト ID X-FM-Data-OAuth-Identifier: 識別子引数 |
| 引数 |
空の中カッコ。例: オプションで |
| 応答 | アクセストークン、空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 応答で X-FM-Data-Access-Token ヘッダが返されます。これは、以降の API 呼び出しで使用するセッショントークンです。 例: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
OAuth 引数を JSON 形式で取得するには:
-
次の URL と HTTP GET メソッドを使用することにより、サポートされている OAuth プロバイダの一覧を取得します:
https://<ホスト>/fmws/oauthproviderinfo<ホスト> は FileMaker Server 展開内のマスタマシンの IP アドレスまたはドメイン名または FileMaker Cloud for AWS ホストの IP アドレスまたはドメイン名です。一覧が JSON 形式で返されます。
- サポートされている OAuth プロバイダを選択してセッションの追跡 ID を取得します。
-
次の URL と HTTP GET メソッドを使用します:
http://<ホスト>/oauth/getoauthurl?trackingID=tracking-ID&provider=OAuth-provider&address=127.0.0.1&X-FMS-OAuth-AuthType=2<ホスト> は FileMaker Server 展開内のマスタマシンの IP アドレスまたはドメイン名または FileMaker Cloud for AWS ホストの IP アドレスまたはドメイン名、tracking-ID は開発者がセッション用に生成した追跡 ID、OAuth-provider は選択した OAuth プロバイダの名前です。
このリクエストの HTTP ヘッダには次の情報を含める必要があります:
- X-FMS-Application-Type: 9
- X-FMS-Application-Version: 15
- X-FMS-Return-URL: http://127.0.0.1/
- X-FMS-Request-ID データの応答ヘッダを読み取ります。この応答ヘッダにはヘッダの X-FM-Data-OAuth-Request-ID 文字列に使用する OAuth リクエスト ID が含まれています。
- X-FMS-Return-URL データの応答ヘッダを読み取ります。この引数で返された URL を呼び出すことによって、ユーザが OAuth プロバイダから認証を受けられるようになります。
- OAuth プロバイダから返される「識別子」はヘッダの X-FM-Data-OAuth-Identifier 文字列に使用する OAuth 識別子の引数です。
FileMaker Pro Advanced ヘルプの「OAuth アカウントアクセスの編集」を参照してください。
FileMaker ID アカウントを使用したデータベースセッションへのログイン
FileMaker Cloud で共有されるファイルの場合、ユーザは FileMaker ID アカウントで認証されます。FileMaker ID アカウントは FileMaker ID アイデンティティプロバイダシステムで定義されます。
FileMaker ID アカウントを使用した共有データベースにログインするには、HTTP POST メソッドを使用して共有データベースの名前を sessions API エンドポイントで指定します。FileMaker ID トークンはヘッダの Authorization 文字列で指定されます。コードはデータベースへの接続を定義するアクセストークンを受け取ります。この接続は「データベースセッション」と呼ばれます。
| HTTP メソッド | POST |
|---|---|
| URL | /fmi/data/version/databases/database-name/sessions
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ | Content-Type: application/json Authorization: FMID {FMID-token} FMID-token は FileMaker ID アイデンティティプロバイダシステムで提供される FileMaker ID トークンです。FileMaker ID トークンの詳細については、プロダクトドキュメンテーションセンターで FileMaker Customer Console ヘルプを参照してください。 FileMaker Pro Advanced ヘルプの「FileMaker ID アカウントアクセスの編集」を参照してください。 |
| 引数 |
空の中カッコ。例: |
| 応答 | アクセストークン、空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 応答で X-FM-Data-Access-Token ヘッダが返されます。これは、以降の API 呼び出しで使用するセッショントークンです。 例: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
データベースセッションからのログアウト
コードによる共有データベースへのアクセスが完了したら、HTTP DELETE メソッドを使用して共有データベースの名前およびセッションのアクセストークンを sessions API エンドポイントで指定します。コードがデータベースセッションからログアウトしていない場合、アクセストークンを指定した最後の呼び出しから 15 分後に FileMaker Data API セッションがタイムアウトになると、そのトークンが無効になります。
| HTTP メソッド | DELETE |
|---|---|
| URL | /fmi/data/version/databases/database-name/sessions/session-token
version – リクエストされた FileMaker Data API のバージョン。 database-name – 共有データベースの名前 session-token – データベースセッションの X-FM-Data-Access-Token |
| HTTP ヘッダ | Content-Type: application/json |
| 引数 | なし |
| 応答 |
空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メタデータの取得
FileMaker Data API では、次のメタデータの取得をサポートしています:
- ホストに関する製品情報。「製品情報の取得」を参照してください。
- 共有データベースの名前。「データベース名の取得」を参照してください。
- 共有データベース内の使用可能な FileMaker スクリプトの名前。「スクリプト名の取得」を参照してください。
- 共有データベース内の使用可能なレイアウトの名前。「レイアウト名の取得」を参照してください。
- 共有データベース内の特定のレイアウトに関するその他のメタデータ。「レイアウトメタデータの取得」を参照してください。
製品情報の取得
ホストに関する製品情報を取得するには、productInfo API エンドポイントと HTTP GET メソッドを使用します。
| HTTP メソッド | GET |
|---|---|
| URL |
形式: /fmi/data/version/productInfo
|
| HTTP ヘッダ | なし |
| 引数 | なし |
| 応答 |
エラーコード 0 を表示するメッセージ配列。「エラー応答」を参照してください。 次のメタデータを含む応答のボディ:
例: {
"response": {
"productInfo": {
"buildDate": "01/30/2020",
"dateFormat": "MM/dd/yyyy",
"timeStampFormat": "MM/dd/yyyy HH:mm:ss",
"version": "18.0.1.30",
"timeFormat": "HH:mm:ss",
"name": "FileMaker Data API Engine"
}
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
|
データベース名の取得
FileMaker Data API を使用して共有されアクセスできるすべてのデータベースのデータベース名を取得するには、databases API エンドポイントと HTTP GET メソッドを使用します。
| HTTP メソッド | GET |
|---|---|
| URL | 形式: fmi/data/version/databases
|
| HTTP ヘッダ |
Authorization ヘッダは Admin Console の [クライアントアプリケーションでのデータベースのフィルタ] 設定によって変わります。
|
| 引数 | なし |
| 応答 |
データベース名の一覧を含むデータベース配列、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"databases": [{
"name": "Customers"
}, {
"name": "Sales"
}]
},
"messages": [{
"code": "0",
"message": "OK"
}]
}
「エラー応答」を参照してください。 |
スクリプト名の取得
指定したデータベースに使用できるすべてのスクリプトのスクリプト名を取得するには、scripts API エンドポイントと HTTP GET メソッドを使用します。
| HTTP メソッド | GET |
|---|---|
| URL | 形式: /fmi/data/version/databases/database-name/sessions
|
| HTTP ヘッダ | Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし |
| 応答 |
スクリプト名およびスクリプトフォルダの一覧を含むスクリプト配列、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"scripts": [
{
"name": "GotoFirst",
"isFolder": false
},
{
"name": "A Folder",
"isFolder": true,
"folderScriptNames": [
{
"name": "script1",
"isFolder": false
},
{
"name": "-",
"isFolder": false
},
{
"name": "script2",
"isFolder": false
},
{
"name": "Another Folder",
"isFolder": true,
"folderScriptNames": [
{
"name": "script3",
"isFolder": false
}
]
},
{
"name": "script4",
"isFolder": false
}
]
}
]
},
"messages": [
{
"message": "OK",
"code": "0"
}
]
}
「エラー応答」を参照してください。 |
レイアウト名の取得
指定したデータベースに使用できるすべてのレイアウトのレイアウト名を取得するには、layouts API エンドポイントと HTTP GET メソッドを使用します。
| HTTP メソッド | GET |
|---|---|
| URL | 形式: /fmi/data/version/databases/database-name/layouts
|
| HTTP ヘッダ | Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし |
| 応答 |
レイアウト名の一覧を含むレイアウト配列、およびエラーコード 0 を表示するメッセージ配列。 例: {
"messages": [
{
"message": "OK",
"code": "0"
}
],
"response": {
"layouts": [
{
"name": "Customers"
},
{
"name": "Details"
},
{
"folderLayoutNames": [
{
"name": "Mark as sent"
},
{
"name": "Find Unsent"
}
],
"isFolder": true,
"name": "Package Management"
}
]
}
}
「エラー応答」を参照してください。 |
レイアウトメタデータの取得
レイアウト、ポータル、および値一覧のフィールドを含むレイアウトメタデータを取得するには、layouts API エンドポイントと HTTP GET メソッドを使用してレイアウト名を指定します。
| HTTP メソッド | GET |
|---|---|
| URL | 形式 1: /fmi/data/version/databases/database-name/layouts/layout-name
形式 2: /fmi/data/version/databases/database-name/layouts/layout-name?recordId=record-id
|
| HTTP ヘッダ | Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし |
| 応答 |
fieldMetaData、portalMetaData および valueLists 配列を含む応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"fieldMetaData": [
{
"name": "CustomerName",
"type": "normal",
"displayType": "editText",
"result": "text",
"valueList": "Text",
"global": false,
"autoEnter": false,
"fourDigitYear": false,
"maxRepeat": 1,
"maxCharacters": 0
"notEmpty": false,
"numeric": false,
"timeOfDay": false,
"repetitionStart": 1,
"repetitionEnd": 1
}
],
"portalMetaData": {},
"valueLists": [
{
"name": "Region",
"type": "customList",
"values": [
{
"displayValue": "West",
"value": "West"
}
,
{
"displayValue": "East",
"value": "East"
}
]
}
]
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
「エラー応答」を参照してください。 |
メモ
- 動的な値一覧の場合、リクエストに URL の一部として
recordId引数が含まれないときに空の値一覧を返します。
レコードの操作
レコードの作成
レコードを作成するには、HTTP POST メソッドを使用してデータベース名とレイアウトを records API エンドポイントで指定します。
| HTTP メソッド | POST |
|---|---|
| URL |
/fmi/data/version/databases/database-name/layouts/layout-name/records
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ | Content-Type: application/json Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | 目的のレイアウト内にあるフィールドに値を指定するフィールド/値ペアが含まれた JSON 形式のレコードデータ。portalData の指定を使用してレイアウト上にある関連レコードまたはポータルをこのデータで指定することもできます。FileMaker Pro Advanced のインスペクタに表示されるオブジェクト名か、関連テーブル名のいずれかをポータル名にすることができます。 例: {"fieldData":
{
"文字列フィールド": "値 1",
"数字フィールド": 99.99,
"繰り返しフィールド (1)" : "フィールド値"
}
}
メモ: 各フィールドのデフォルト値が空のレコードを作成するには、引数として空のデータオブジェクトを JSON 形式で指定します。 例: {"fieldData":
{
}
}
リクエストのボディに |
| 応答 |
作成されたレコードのレコード ID、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"recordId":"147",
"modId":"0"
},
"messages": [
{
"code": "0",
"message":"OK"
}
]
}
「エラー応答」を参照してください。 |
メモ
- FileMaker Data API を使用してレコードを作成する際はフィールドの入力値の制限が強制されます。データがフィールドの入力値の制限を満たしていない場合、エラーメッセージが返されてレコードは作成されません。
レコードの編集
レコードを編集するには、HTTP PATCH メソッドを使用してデータベース名、レイアウト、およびレコード ID を records API エンドポイントで指定します。
| HTTP メソッド | PATCH |
|---|---|
| URL |
/fmi/data/version/databases/database-name/layouts/layout-name/records/record-id
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ |
Content-Type: application/json Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | 更新するフィールド/値ペアが含まれた JSON 形式のレコードデータ。portalData の指定を使用してレイアウト上にある関連レコードまたはポータルをこのデータで指定することもできます。FileMaker Pro Advanced のインスペクタに表示されるオブジェクト名か、関連テーブル名のいずれかをポータル名にすることができます。 指定したフィールドのみが更新されます。レコード内の他のフィールドは変更されません。 オプションの引数: 修正 ID ( 例: {
"fieldData":
{
"First Name": "Joe"
},
"portalData":
{
"JobsTable": [
{
"recordId": "70",
"modId": "4",
"JobsTable::Name": "Contractor"
}
]
}
}
リクエストのボディに |
| 応答 |
応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"modId": "3"
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
「エラー応答」を参照してください。 |
メモ
- FileMaker Data API を使用してレコードを編集する際はフィールドの入力値の制限が強制されます。データがフィールドの入力値の制限を満たしていない場合、エラーメッセージが返されてレコードは更新されません。
-
関連レコードを削除するには、
deleteRelated構文を使用する必要があります。単一のレコードを削除する場合の例:
"deleteRelated" : "Orders.3"複数のレコードを削除する場合の例:
"deleteRelated" : ["Orders.7", "Orders.9"]
レコードを複製する
レコードを複製するには、HTTP POST メソッドを使用してデータベース名、レイアウト名、およびレコード ID を records API エンドポイントで指定します。
| HTTP メソッド | POST |
|---|---|
| URL |
/fmi/data/version/databases/database-name/layouts/layout-name/records/record-id
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ |
Content-Type: application/json Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし リクエストのボディに |
| 応答 |
新規レコードのレコード ID、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"recordId": "7",
"modId": "0"
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
「エラー応答」を参照してください。 |
レコードの削除
レコードを削除するには、HTTP DELETE メソッドを使用してデータベース名、レイアウト、およびレコード ID を records API エンドポイントで指定します。
| HTTP メソッド | DELETE |
|---|---|
| URL | /fmi/data/version/databases/database-name/layouts/layout-name/records/record-id
version – リクエストされた FileMaker Data API のバージョン。 URL に |
| HTTP ヘッダ | Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし |
| 応答 |
空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
単一のレコードの取得
レコードを取得するには、HTTP GET メソッドを使用してデータベース名、レイアウト、およびレコード ID を records API エンドポイントで指定します。ポータル情報を指定して返される関連レコードの数を制限することもできます。
| HTTP メソッド | GET |
|---|---|
| URL | 形式 1: /fmi/data/version/databases/database-name/layouts/layout-name/records/record-id
version – リクエストされた FileMaker Data API のバージョン。 portal キーワードについて: URL の portal 部分はオプションです。レイアウトに複数のポータルが含まれている場合は、パフォーマンスを向上させるためにポータル名を指定します。portal 部分を省略した場合、呼び出しによってレイアウト上のすべてのポータルにあるすべての関連レコードが返されます。
異なるレイアウトのコンテキストにある応答データが必要な場合は、URL 内の URL に |
| HTTP ヘッダ | Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし |
| 応答 | JSON 形式のレコードデータおよびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メモ
- 特定のポータル行にデータを返すには、
_offset.portal-nameおよび_limit.portal-name.FileMaker Pro Advanced のインスペクタに表示されるオブジェクト名か、関連テーブル名のいずれかをポータル名にすることができます。ポータル行のオフセット値と制限値を省略した場合、デフォルトのオフセット値 1 とポータルレコードのデフォルトの制限値 50 が使用されます。
レコードの範囲の取得
レコードの範囲を取得するには、HTTP GET メソッドを使用してデータベース名、レイアウト、および開始レコードとレコード数を指定する追加情報を records API エンドポイントで指定します。オプションでレコードのソート順を指定できます。ポータル情報を指定して返される関連レコードの数を制限することもできます。
| HTTP メソッド | GET |
|---|---|
| URL |
形式 1 (最大で最初の 100 のレコードを返す):
version – リクエストされた FileMaker Data API のバージョン。
portal キーワードについて: URL の portal 部分はオプションです。レイアウトに複数のポータルが含まれている場合は、パフォーマンスを向上させるためにポータル名を指定することができます。portal 部分を省略した場合、呼び出しによってレイアウト上のすべてのポータルにあるすべての関連レコードが返されます。
異なるレイアウトのコンテキストにある応答データが必要な場合は、URL 内の URL に |
| HTTP ヘッダ | Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | なし |
| 応答 |
JSON 形式のレコードデータおよびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メモ
- オフセット値と制限値を省略した場合、デフォルトのオフセット値 1 とレコードのデフォルトの制限値 100 が使用されます:
_offset=1&_limit=100 - ソート順のキーワードを省略した場合、デフォルトは
ascendになります。たとえば、&_sort=[{ "fieldName": "recordId" }]は次のように処理されます:&_sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }] - 特定のポータル行にデータを返すには、
_offset.portal-nameおよび_limit.portal-name.FileMaker Pro Advanced のインスペクタに表示されるオブジェクト名か、関連テーブル名のいずれかをポータル名にすることができます。ポータル行のオフセット値と制限値を省略した場合、デフォルトのオフセット値 1 とポータルレコードのデフォルトの制限値 50 が使用されます。
オブジェクトデータのアップロード
オブジェクトデータをアップロードするには、HTTP POST メソッドを使用してデータベース名、レイアウト名、レコード ID、フィールド名、およびフィールド繰り返しを containers API エンドポイントで指定します。
| HTTP メソッド | POST |
|---|---|
| URL | 形式: /fmi/data/version/databases/database-name/layouts/layout-name/records/record-id/containers/field-name/field-repetition
|
| HTTP ヘッダ | Content-Type: multipart/form-data Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | オブジェクトフィールドのオブジェクトが multipart/form-data の指定をサポートするライブラリを使用してください。 |
| 応答 |
空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メモ
- オブジェクトフィールドは指定されたレイアウトのテーブルオカレンスにあるフィールドである必要があります。関連テーブル内のオブジェクトフィールドを指定することはできません。
- FileMaker Data API はすべての MIME タイプを許可します。MIME タイプを FileMaker ソフトウェアまたは Web サーバーでサポートされるタイプに制限するためのチェックは実行されません。
- FileMaker Data API では、オブジェクトフィールドデータがアップロードされている場合、マスタマシン上のキャッシュフォルダにそのオブジェクトフィールドデータをキャッシュしますが、リクエストが完了するとキャッシュデータは削除されます。
検索の実行
検索を実行するには、HTTP POST メソッドを使用してデータベース名およびレイアウトと、クエリーフィールド、クエリー条件、ソート順、開始レコード、およびレコード数を指定する追加情報を _find API エンドポイントで指定します。ポータル情報を指定して返される関連レコードの数を制限することもできます。
| HTTP メソッド | POST |
|---|---|
| URL |
/fmi/data/version/databases/database-name/layouts/layout-name/_find
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ |
Content-Type: application/json Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | フィールドおよび検索条件を指定する JSON 形式のクエリー。除外リクエスト、ソート順、開始レコード (オフセット)、レコード数 (制限)、および返される関連レコード数を制限するためのポータルを指定するオプション引数。 異なるレイアウトのコンテキストにある応答データが必要な場合は、 例: {
"query":[
{"Group": "=Surgeon"},
{"Work State" : "NY", "omit" : "true"}],
"sort":[
{"fieldName": "Work State","sortOrder": "ascend"},
{"fieldName": "First Name", "sortOrder": "ascend"} ]
}
オフセット、制限、およびポータルの使用例: {
"query":[
{"Group": "=Surgeon"},
{"Work State" : "NY", "omit" : "true"}],
"portal": ["Portal1","Portal2"],
"limit": "10",
"offset": "1",
"offset.Portal1": "1",
"limit.Portal1": "5",
"layout.response": "Doctors"
}
リクエストのボディに |
| 応答 |
JSON 形式のレコードデータおよびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メモ
- レコードをソートして返すと時間がかかる可能性があります。リクエストされたレイアウトのフィールドの数を制限、およびコメントを含むフィールドを除外するとレコードのダウンロード時間を短縮できます。
- 関連セットで表示するレコードと行の数を制限するには、offset.portal-name および limit.portal-name 引数を指定します。
- 検索条件としてグローバルフィールドを指定することはできません。検索条件でグローバルフィールドを指定すると、エラーメッセージが返されます。代わりに、検索条件の前にグローバルフィールドの値を設定してください。「グローバルフィールドの値の設定」を参照してください。
グローバルフィールドの値の設定
グローバルフィールドの値を設定するには、HTTP PATCH メソッドを使用してデータベース名を globals API エンドポイントで指定します。
| HTTP メソッド | PATCH |
|---|---|
| URL | /fmi/data/version/databases/database-name/globals
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ |
Content-Type: application/json Authorization: Bearer session-token。session-token はデータベースセッションに固有の X-FM-Data-Access-Token の値です。 |
| 引数 | 設定するグローバルフィールドを指定するフィールド/値ペアが含まれる JSON オブジェクト。グローバルフィールドは完全修飾フィールド名 (テーブル名::フィールド名) を使用して指定する必要があります。 例: { "globalFields":
{
"baseTable::gCompany":"FileMaker",
"baseTable::gCode":"95054"
}
}
|
| 応答 |
空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
|
FileMaker スクリプトの実行
FileMaker Data API で FileMaker スクリプトを実行することができます:
scriptAPI エンドポイントと HTTP GET メソッドを使用する方法。「スクリプトの実行」を参照してください。- リクエストのボディに
script.prerequest、script.presort、およびscript引数を含めることで、別のリクエストの一部として実行する方法。「別のリクエストによるスクリプトの実行」を参照してください。
スクリプトの実行
FileMaker スクリプトを独立して実行するには、script API エンドポイントと HTTP GET メソッドを使用する方法。
| HTTP メソッド | GET |
|---|---|
| URL | /fmi/data/version/databases/database-name/layouts/layout-name/script/script-name
version – リクエストされた FileMaker Data API のバージョン。 |
| HTTP ヘッダ | Content-Type: application/json |
| 引数 | script.param - script-name で指定されているスクリプトの引数として使用されるテキスト文字列。 |
| 応答 |
空の応答のボディ、およびエラーコード 0 を表示するメッセージ配列。 例: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
「エラー応答」を参照してください。 |
メモ
- FileMaker Data API を使用してスクリプトを実行する場合、スクリプトに固有の名前がついていることを確認してください。同じ名前の複数のスクリプトがある場合、FileMaker Data API はスクリプトが異なるフォルダにあっても、呼び出すスクリプトを制御できません。
別のリクエストによるスクリプトの実行
FileMaker スクリプトを別のリクエストの一部として実行するには、リクエストのボディに script.prerequest、script.presort、および script 引数を含めます。
| 引数 | 値 |
|---|---|
script |
API の呼び出しで指定されている処理 (取得、作成、編集、複製、削除、検索) の後や以降のソートの後に実行されるスクリプトの名前。 |
script.param |
script で指定されているスクリプトの引数として使用されるテキスト文字列。 |
script.prerequest |
API の呼び出しや以降のソートで指定されている処理の前に実行されるスクリプトの名前。 |
script.prerequest.param |
script.prerequest で指定されているスクリプトの引数として使用されるテキスト文字列。 |
script.presort |
API の呼び出しで指定されている処理の後で実行されるが、以降のソートの前に実行されるスクリプトの名前。 |
script.presort.param |
script.presort で指定されているスクリプトの引数として使用されるテキスト文字列。 |
スクリプトの実行順序
script.prerequest、script.presort、および script 引数を単一の API 呼び出しに指定することができます。各キーワードは 1 度だけ指定することができます。ホストでは、これらの引数を API 呼び出しの一部として次の順序で処理します:
- URL で指定されたレイアウトに移動します。
script.prerequestで指定されているスクリプトを実行します (指定されている場合)。- API 呼び出しで指定されている処理 (取得、作成、編集、複製、削除、検索) を実行します。
script.presortで指定されているスクリプトを実行します (指定されている場合)。- API 呼び出しで指定されているソートを実行します:
- レコードの範囲の取得では、
_sort引数で指定されているソートを実行します。 - 検索の実行では、
sort引数で指定されているソートを実行します。
- レコードの範囲の取得では、
scriptで指定されているスクリプトを実行します (指定されている場合)。- offset 引数および limit 引数の適用された API 呼び出しの結果セットが返されます (指定されている場合)。
メモ
- HTTP GET メソッドおよび HTTP DELETE メソッドを使用した呼び出しでは、スクリプト引数が URL 引数として含まれています。「単一のレコードの取得」、「レコードの範囲の取得」、および「レコードの削除」を参照してください。
- HTTP POST メソッドおよび HTTP PATCH メソッドを使用した呼び出しでは、リクエストのボディにスクリプト引数が含まれています。「レコードの作成」、「レコードの編集」、および「検索の実行」を参照してください。
- スクリプト引数である
script.param、script.prerequest.param、およびscript.presort.paramには、1 つのテキスト文字列のみを指定することができます。複数の引数を渡すには、それらの引数を区切る文字列を作成し、スクリプトが個々の引数を解析するようにします。たとえば、「param1|param2|param3」は「|」文字を「param1%7Cparam2%7Cparam3」のように URL エンコードした一覧として渡します。 - スクリプトの結果は
scriptResult、scriptResult.prerequest、およびscriptResult.presort引数を使用して JSON データで返されます。スクリプトエラーはscriptError、scriptError.prerequest、およびscriptError.presort引数を使用して JSON データで返されます。(スクリプトエラーが返される際は、HTTP ステータスコードは使用されません。)
例:
https://<ホスト>/fmi/data/v1/databases/customers/layouts/entry/records/14?script=UpdateProcessing&script.param=14
例:
{"query":[{"Title":"Office Manager"}], "script.prerequest":"Eliminate duplicates"}
エラー応答
エラーが発生した場合、FileMaker Data API は次のステータスコードを返します:
- 標準的な HTTP のエラーの場合は HTTP 400 番台のステータスコード
- FileMaker のエラーの場合は HTTP 500 のステータスコード
| HTTP ステータスコード | HTTP カテゴリ | 説明 |
|---|---|---|
| 400 | 不正なリクエスト | リクエストが不完全または無効なため、サーバーが処理できない場合に発生します。 |
| 401 | 権限がありません | クライアントが API にアクセスする権限がない場合に発生します。データベースセッションへのログイン試行中にこのエラーが起きた場合、指定されたユーザアカウントまたはパスワードに問題があります。他の呼び出しでこのエラーが起きた場合、アクセストークンが指定されていないか、または無効です。 |
| 403 | 禁止されています | クライアントは認証されているが、呼び出しにより別の理由で禁止されている処理が試行された場合に発生します。 |
| 404 | 見つかりません | 呼び出しが無効な URL スキーマの URL を使用した場合に発生します。指定した URL に構文エラーがないか確認してください。 |
| 405 | メソッドが使用できません | 呼び出しで誤った HTTP メソッドが使用された場合に発生します。 |
| 415 | サポートされていないメディアタイプ | 必要なヘッダが見つからないか、またはリクエストに対して正しくない場合に発生します:
|
| 500 | FileMaker エラー | FileMaker のエラーメッセージとエラーコードが含まれます。FileMaker Pro Advanced ヘルプの「FileMaker エラーコード」を参照してください。 |
メモ
- FileMaker Data API エンジンが実行されていないか、またはアクセスできない場合、返されるエラーコードまたはエラーメッセージは Web サーバー (Apache または IIS) によって変わります。
- 返されるその他の HTTP ステータスコードの詳細については、www.w3.org を参照してください。
FileMaker Data API ソリューションの共有、テスト、監視
FileMaker Data API ソリューションの共有
- 「FileMaker Data API アクセス用のデータベースの準備」に記載されているすべての手順を完了します。
- FileMaker Data API アクセスが Admin Console で有効に設定されて正しく構成されていることを確認します。プロダクトドキュメンテーションセンターを参照してください。
- Web サーバーおよび FileMaker Data API エンジンが実行されていることを確認します。
-
通信に暗号化を使用します。
FileMaker Data API では、REST API アプリケーションで HTTPS 接続を使用する必要があります。HTTPS 接続では、通信に SSL (Secure Sockets Layer) が使用されます。
FileMaker Server は、FileMaker, Inc. によって署名された標準の SSL 証明書を提供しますが、サーバー名の検証は行われません。この FileMaker デフォルト証明書はテスト用にのみ利用できます。実際に運用環境で使用する場合はカスタム SSL 証明書が必要です。FileMaker Server インストールおよび構成ガイドを参照してください。
FileMaker Data API を呼び出すために使用する言語またはテクノロジーは、Web サーバーとの通信に TLS (Transport Layer Security) v1.2 をサポートしている必要があります。
FileMaker Data API ソリューションのテスト
FileMaker Data API ソリューションを実際の運用環境に展開する前に、意図したとおりに機能することを確認します。
- レコードの検索、追加、削除などの機能をさまざまなアカウントとアクセス権セットでテストします。
- 異なるアカウントでテストして、アクセス権セットが期待どおりに動作することを確認します。権限のないユーザがデータにアクセス、または変更できないようにしてください。
- 異なるオペレーティングシステムから呼び出してもソリューションが同じように動作することをテストします。
FileMaker Data API ソリューションの監視
サーバー管理者は Admin Console を使用して FileMaker Data API エンジンの起動と停止、FileMaker Data API クライアントの監視、FileMaker Data API 呼び出しの使用の追跡、および FileMaker Data API ログファイルのダウンロードを実行できます。
| 目的 | 用途 |
|---|---|
| FileMaker Data API エンジンを起動または停止する |
Admin Console の [コネクタ] > [FileMaker Data API] タブ。FileMaker Server ヘルプの「FileMaker Server コンポーネントの起動または停止」またはプロダクトドキュメンテーションセンターで FileMaker Cloud 製品のマニュアルを参照してください。 FileMaker Server で CLI コマンドを使用することもできます。「CLI ヘルプ」を参照してください。 |
| FileMaker Data API クライアントを監視する |
Admin Console の [データベース] ページにあるクライアントの一覧。このページには、クライアントの詳細とアクセスされているデータベースの詳細が表示されます。このページから FileMaker Data API クライアントを接続解除できますが、クライアントにメッセージを送信することはできません。 FileMaker Server ヘルプの「クライアントの管理」またはプロダクトドキュメンテーションセンターで FileMaker Cloud 製品のマニュアルを参照してください。 |
| FileMaker Data API 呼び出しの使用を追跡する |
Admin Console の [コネクタ] > [FileMaker Data API] タブ。このタブには、ご利用中のライセンスで設定されている FileMaker Data API 年間制限、前回の年間リセット日から送信されたデータ量、およびライセンスの年間リセット日が表示されます。
|
| FileMaker Data API のログを表示する |
FileMaker Data API クライアントがデータベースに接続している間、クライアントに関する使用状況データが「fmdapi.log」に記録されます。 FileMaker Server ヘルプの「FileMaker Data API ログ」またはプロダクトドキュメンテーションセンターで FileMaker Cloud 製品のマニュアルを参照してください。 |
FileMaker Data API と Tableau との統合
Tableau との統合について
Web データコネクタを使用して共有 FileMaker データベースと Tableau 間の接続を定義します。Web データコネクタは JSON 形式の REST API 呼び出しを使用できるサンプル実装です。この接続では FileMaker Data API を使用して共有 FileMaker データベースから Tableau へデータをインポートします。
FileMaker Server または FileMaker Cloud 製品を使用して FileMaker データベースを共有します。これらのホストは次の Tableau 製品と統合することができます:
Tableau Desktop。最小バージョン 10、Windows または macOS 用。FileMaker Web Data Connector for Tableau Desktop を使用して Tableau Desktop との接続を定義します。
Tableau Server。オンプレミスでのインストールまたは顧客によるホスト。Tableau Server 上で FileMaker Web Data Connector for Tableau Server をホストします。
Tableau Cloud。ローカルの Tableau Server インスタンスを動作させてデータを Tableau Cloud に転送します。Tableau Server 上で FileMaker Web Data Connector for Tableau Server をホストします。
Tableau Online。Tableau Bridge を使用する必要があります。
Web データコネクタの必要条件
FileMaker Web Data Connector for Tableau には次が必要です:
- インポートするデータが含まれているパスワードで保護された FileMaker Pro Advanced データベース。データベースは FileMaker Server または FileMaker Cloud ホストで共有する必要があります。FileMaker Server および FileMaker Cloud for AWS では、FileMaker ファイル認証および OAuth 認証をサポートしています。FileMaker Cloud では FileMaker ID 認証が必要です。
-
有効な REST API エンドポイント。
FileMaker Server では、エンドポイントは Web サービスに必要な情報を提供する HTML 接続ポイントです。エンドポイントの形式は次のとおりです:
https://<ホスト名>/fmi/data/version/tableau/fm_connector.html
<ホスト名>は FileMaker Server の完全修飾ホスト名です。例:
https://myserver.mycompany.com/fmi/data/v1/tableau/fm_connector.html ホスト上の有効なカスタム SSL 証明書。FileMaker Web Data Connector for Tableau では、有効なカスタム SSL 証明書がなければデータをインポートできません。
メモ: ホストでサブジェクトの別名 (SAN) 証明書を使用する場合、ホスト名は SAN 証明書で使用されている共通名と一致している必要があります。
Tableau へのデータのインポート準備
「FileMaker Data API アクセス用のデータベースの準備」の手順に従い、インポート用のレイアウトを定義して FileMaker Data API アクセス用のデータベースを有効にします。
メモ: Tableau にデータをインポートするには、レコードデータのあるレコードがテーブルに 1 つ以上含まれている必要があります。
次の FileMaker フィールドタイプは Tableau データ型としてインポートされます。
| FileMaker フィールドタイプ | Tableau データ型 |
|---|---|
| テキスト | string |
| 日付 | date |
| 時刻 | string |
| タイムスタンプ | datetime |
| 数字 | float |
次の FileMaker フィールドタイプは Tableau へのインポート時にサポートされません:
- オブジェクトフィールド
- 集計フィールド。FileMaker からインポートするデータに基づいて Tableau で集計フィールドを作成することができます。
- 計算フィールド。FileMaker からインポートするデータに基づいて Tableau で計算フィールドを作成することができます。
- グラフデータ
- FileMaker Pro Advanced ポータルからのデータ。関連レコードからデータをインポートするには、関連テーブルに基づく FileMaker Pro Advanced レイアウトを作成するか、または別の FileMaker Pro Advanced テーブルから Tableau へデータをインポートしてから Tableau でテーブルを結合します。
- 繰り返しフィールドの [繰り返しを表示] 設定の表示に複数の値が含まれているフィールドの繰り返し。単一の繰り返しはサポートされます。
- 数字フィールドの数値以外の値。Tableau が数字フィールドで数値以外の値を検出した場合、そのデータはインポートされません。
FileMaker Pro Advanced でフィールド名として使用されている単語を使用しないでください。
Tableau でのデータ接続の設定
Web データコネクタの使い方を説明する Tableau 製品のオンラインヘルプの指示に従ってください。
たとえば、FileMaker Server Web Data Connector for Tableau Desktop でデータ接続を設定するには、次の操作を行います:
- Tableau Desktop の [接続] (画面の左側) で、[その他のサーバー...] > [Web データコネクタ] を選択します。
- FileMaker Server エンドポイントの URL を入力します:
https://<ホスト名>/fmi/data/v1/tableau/fm_connector.html
<ホスト名>は FileMaker Server の完全修飾ホスト名です。 -
[FileMaker ファイルからのデータのインポート] ダイアログボックスで次の操作を行います:
-
次の情報を入力するか OAuth アイデンティティプロバイダを使用して FileMaker Pro Advanced データベースにサインインします。
- [ソースデータベース名]: FileMaker Pro Advanced データベースの名前
- [ソースレイアウト名]: FileMaker Pro Advanced レイアウトの名前
- [アカウント名]: fmrest アクセス権のある FileMaker Pro Advanced アカウントの名前
- [パスワード]: FileMaker Pro Advanced アカウントのパスワード
- [増分更新を有効にする] を選択して増分更新を有効にします。
-
- [FileMaker データのインポート] をクリックします。
Tableau によりデータがインポートされます。処理時間はインポートするレコード数、サーバーの負荷、およびネットワークスループットによって変わります。Tableau によって FileMaker Pro Advanced フィールド名およびデータがディメンションおよびメジャーにマッピングされます。通常、文字列データはディメンションにマッピングされ、数値データはメジャーにマッピングされます。マッピングはインポート中に自動的に行われますが、カスタマイズすることもできます。
メモ
-
[ソースレイアウト名] を指定する際はレイアウト名が固有であることを確認してください。データベースに同じ名前のレイアウトが 2 つある場合、Tableau データ接続ではその 2 つを区別できません。Tableau には名前が 1 つのみ表示され、それが必要としていたレイアウトではない可能性もあります。
- Tableau でデータ接続の設定をする場合、ユーザに認証を求めるオプションを選択しないでください。
-
新規レコードのみをインポートするには、[増分更新を有効にする] を使用します。
- 増分更新を有効にして FileMaker データをインポートした後に、Tableau の [シート] タブを選択してワークシートに移動します。
- [データ] > [FM: データベース名 / レイアウト名] > [抽出] > [更新 (増分)] を選択します。
- [データソース] タブを選択します。
- [更新] をクリックして新規レコードを表示します。
- 増分更新を有効にしても、共有されている FileMaker データベースと Tableau 間に継続的なライブ接続は確立されません。増分更新を手動で実行する必要があります。
- 増分更新では、新規レコードのみがインポートされます。変更または削除された FileMaker Pro Advanced レコードは更新されません。変更データを取得するか削除されたレコードを取り除くには、Tableau でワークブックを新規作成してデータを再インポートする必要があります。
- 増分更新では、-recordId という名前のフィールドが作成されます。このフィールドを変更すると、増分更新を実行できなくなる可能性があります。
- Tableau で、インポートされたスキーマおよびデータを変更できます。ただし、Tableau でスキーマまたはデータを変更しても、これらの変更は FileMaker Pro Advanced ファイルに送信されません。
- FileMaker Pro Advanced ファイルでスキーマを変更した場合は、Tableau でワークブックを新規作成してデータを再インポートする必要があります。
- Tableau ワークブックを閉じてから再度開くと、増分インポートが動作しなくなります。
- Tableau へのデータ接続が確立されると、次の状況を考慮して、ワークブックが閉じられるまで FileMaker Web データコネクタによってユーザアカウントとパスワードがキャッシュされます:
- Tableau に接続している間に FileMaker セッションがタイムアウトになった場合、FileMaker Web データコネクタは共有データベースへのユーザの再接続を試行します。
- Tableau 接続が期限切れになった場合、Tableau ワークブックが開いている限り、FileMaker Web データコネクタは共有データベースへの再接続を試行します。
- Tableau の更新トークンが期限切れになった場合、Tableau Desktop でデータソースを再パブリッシュする必要があります。
- ワークブックを閉じてから再度開いた場合は、最初のデータインポート時にアカウント名とパスワードを再入力する必要があります。
- Tableau の [データソース] ページには、最大 1,000,000 (100 万) 行が表示されます。これより多くのレコードがインポートされた場合も同様です。
- データベース名、テーブル名、またはレイアウト名に特殊文字を使用すると、Tableau でデータ接続を確立できなくなります。