FileMaker 16 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 を使用したデータベースの作成。 データベースの設計の基礎、ならびにフィールド、リレーションシップ、レイアウト、ポータル、およびオブジェクトの概念について理解している必要があります。 FileMaker Pro ヘルプを参照してください。
- FileMaker Server を使用したソリューションの共有。 FileMaker Server の展開方法、共有ソリューションへのアクセスを有効にする方法、および FileMaker Server Admin Console を使用して共有ソリューションを監視する方法について理解している必要があります。 FileMaker Server ヘルプを参照してください。
- POST、GET、PUT、および DELETE メソッドと JSON 形式のデータを呼び出すサーバーサイドアプリケーションまたは Web サービスでの REST API の使用。 任意のプログラミング言語またはプログラミングツールを使用できる必要があります。
FileMaker Data API を使用するには次の手順に従います:
- FileMaker Pro を使用して FileMaker Data API アクセス用のデータベースを準備します。 データベースを新規作成するか、または既存のデータベースを準備します。 「FileMaker Data API アクセス用のデータベースの準備」を参照してください。
- 共有ソリューション内のレコードを検索、作成、編集、削除する FileMaker Data API メソッドを呼び出すコードを作成します。 「FileMaker Data API 呼び出しの作成」を参照してください。
- FileMaker Server を使用してソリューションを共有して FileMaker Data API アクセスを有効にします。 「FileMaker Data API ソリューションの共有」を参照してください。
- FileMaker Data API アクセスが正しく動作するかをテストします。 「FileMaker Data API ソリューションのテスト」を参照してください。
- Admin Console を使用して共有ソリューションを監視します。 「FileMaker Data API ソリューションの監視」を参照してください。
FileMaker Data API 呼び出しの処理の流れ
-
REST API クライアントが、HTTPS ポート経由で FileMaker Server の Web サーバーに FileMaker Data API 呼び出し (HTTPS リクエスト) を送信します。 FileMaker Pro がインストールまたは実行されている必要はありません。
デフォルトの HTTPS ポートは 443 ですが、サーバー管理者は FileMaker Server のインストール時に別のポートを指定できます。
- 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 ユーザは FileMaker Server で共有されているソリューションに接続してレコードを表示、編集、ソート、または検索できます。 互換性のある Web ブラウザソフトウェアとインターネットまたはイントラネットへのアクセスがあれば、追加のソフトウェアをインストールする必要はありません。 ユーザインターフェースは、FileMaker Pro デスクトップアプリケーションに似ています。 Web ユーザが操作する Web ページおよびフォームは、FileMaker Pro データベースで定義されたレイアウトおよび表示形式によって変わります。
FileMaker WebDirect ガイドを参照してください。
静的公開: データに変更がほとんどない場合、またはユーザによるデータベースへのライブ接続を要求しない場合は静的公開を使用することができます。 静的公開では、FileMaker Pro データをエクスポートして Web ページを作成し、HTML でさらにカスタマイズできます。 データベースの情報が変更されても Web ページは変更されません。ユーザはデータベース自体には接続しません。
FileMaker Pro ヘルプの「静的 Web ページでデータを公開する」を参照してください。
カスタム Web 公開: FileMaker データベースをカスタム Web サイトに統合するには、カスタム Web 公開テクノロジーを使用します。
『FileMaker Server カスタム Web 公開ガイド』を参照してください。
FileMaker Data API アクセス用のデータベースの準備
アクセスするデータの決定
FileMaker Data API で使用する FileMaker Pro データベースを新規作成するか、または既存のデータベースを使用することができます。 データベースを新規作成する場合は、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 ヘルプを参照してください。
FileMaker Data API アクセスの有効化
FileMaker Data API を使用してアクセスする各データベースで [FileMaker Data API でのアクセス] 拡張アクセス権を有効にする必要があります。 データベース内で FileMaker Data API 拡張アクセス権を有効にしない場合、FileMaker Server でデータベースが共有されていても REST API アプリケーションは FileMaker Data API を使用してデータベースにアクセスできません。
データベースへの FileMaker Data API アクセスを有効にするには:
- FileMaker Pro で、[完全アクセス] アクセス権セットが割り当てられているアカウントを使用してデータベースを開きます。 または、[拡張アクセス権の管理] アクセス権が割り当てられているアカウントを使用してデータベースを開くこともできます。
- [セキュリティの管理] ダイアログボックスの [拡張アクセス権] タブで、fmrest 拡張アクセス権を選択して有効にします。
- fmrest 拡張アクセス権を含むアクセス権セットを 1 つ以上のアカウントに割り当てます。
メモ: セキュリティ上の理由から、共有ソリューションへのアクセスを許可するアカウントのアクセス権セットでのみ fmrest 拡張アクセス権を有効にします。
FileMaker Pro ヘルプの「アクセス権セットの作成と編集」を参照してください。
FileMaker Data API 呼び出しの作成
FileMaker Data API の機能
FileMaker Data API は、共有ソリューションのデータにアクセスするための REST API を提供します。 FileMaker Data API を使用すると、コードで次の操作が可能になります:
- 共有ソリューションへのログインまたはログアウト。「データベースへの接続を確立または切断する呼び出し」を参照してください。
- レコードの作成、編集、削除、取得、またはレコードの範囲の取得。 「レコードを操作する呼び出し」を参照してください。
- 検索の実行。「検索を実行する呼び出し」を参照してください。
- グローバルフィールドの値の設定。「グローバルフィールドの値を設定する呼び出し」を参照してください。
FileMaker Data API では、次の操作はサポートされません:
- オブジェクトフィールドへのデータのアップロード
- 外部 ODBC データソースのデータへのアクセス
- FileMaker プラグイン
- FileMaker スクリプトの実行
- スクリプトトリガの実行
FileMaker Data API は FileMaker Pro に表示されるフィールドデータではなく、データベースに保存されているフィールドデータを返します。
FileMaker Data API Reference
FileMaker Server をインストールすると FileMaker Data API Reference ファイルがインストールされます。 このリファレンスファイルには、FileMaker Data API でサポートされるすべての呼び出しに関する詳細情報が含まれています。
- マスタマシンのブラウザウインドウでこのリファレンスを表示するには、次の URL を入力します。
https://localhost/fmi/rest/apidoc/
- リモートマシンのブラウザウインドウでこのリファレンスを表示するには、次の URL を入力します。
https://
<ホスト>
/fmi/rest/apidoc/
<ホスト>
は FileMaker Server が実行されているマスタマシンの IP アドレスまたはホスト名です。 Windows サーバーの場合、リファレンスファイルは次のフォルダ内にあります。
[ドライブ]
:¥Program Files¥FileMaker¥FileMaker Server¥Documentation¥Data API Documentation
[ドライブ]
は FileMaker Server 展開が存在するドライブです。Windows 上のデフォルト以外の場所にインストールした場合、次のようにデフォルトのインストールパスの先頭部分がインストール場所に置き換わります。
[インストール場所]
:¥Documentation¥Data API Documentation- macOS サーバーの場合、リファレンスファイルは次のフォルダ内にあります。
/ライブラリ/FileMaker Server/Documentation/Data API Documentation
データ形式に関する注意点
- すべてのデータ値で HTTP リクエストの標準である URL エンコーディングを使用する必要があります。これはパーセントエンコーディングとも呼ばれます。 たとえば、スラッシュ文字を含むレイアウト名を指定するには、スラッシュ文字をエンコード値「%2F」として指定する必要があります。
- 指定するフィールドおよびポータルは、指定するレイアウト上に存在する必要があります。
- 関連フィールドを指定するには、「
テーブル名::関連フィールド
」という構文を使用する必要があります。 - 2 回以上のフィールドの繰り返しを使用するには、「
テーブル名::関連フィールド(繰り返し数)
」という構文を使用する必要があります。 - レコードを編集する場合は、「
テーブル名::関連フィールド(繰り返し数).レコード ID
」というレコード ID 構文を使用する必要があります。 - オブジェクトフィールドデータの場合、FileMaker Data API はオブジェクトデータのオブジェクトへのパス参照を含む URL を返します。
REST API 呼び出しのコンポーネント
FileMaker Data API 呼び出しは次のコンポーネントで構成されます。
コンポーネント | 説明 |
---|---|
HTTP メソッド (HTTP 動詞) |
FileMaker Data API は次の HTTP メソッドを使用します:
|
HTTP ヘッダ |
FileMaker Data API は次のヘッダを使用します:
|
呼び出し URL | FileMaker Data API の URL はすべて次の文字列から始まります:/fmi/rest/api/ |
JSON 形式の引数データ | ソリューションからのログアウト、レコードの削除、単一のレコードの取得、またはレコードの範囲の取得では必要ありません。 |
データベースへの接続を確立または切断する呼び出し
FileMaker Data API ではアクセストークンを使用してデータベースへの接続を定義します。 以降はその共有ソリューションに対するすべての呼び出しのヘッダでそのアクセストークンを使用する必要があります。 アクセストークンは、ソリューションからログアウトするか、またはそのトークンを指定した最後の呼び出しから 15 分経過するまで有効です (トークンが有効な間は、そのトークンを指定して呼び出しを行うたびにセッションタイムアウトカウンタがゼロにリセットされます)。
ソリューションへのログイン
共有ソリューションにログインするには、HTTP POST メソッドを使用して共有ソリューションの名前を auth
URL で指定します。
アカウント名とパスワードが認証されると、コードはソリューションへの接続を定義するアクセストークンを受け取ります。
HTTP メソッド | POST |
---|---|
URL | /fmi/rest/api/auth/solution solution – 共有データベースの名前 |
HTTP ヘッダ | Content/Type: application/json |
引数 | 共有ソリューションにログインするためのアカウント名とパスワード、およびログイン後に切り替えるレイアウト (JSON 形式)。 例: {
"user":"admin",
"password":"admin",
"layout":"タスク"
} |
応答 | アクセストークン、現在のレイアウト、およびエラーコード 0。 例: {
"errorCode": "0",
"layout": "タスク",
"token": "fdde29fa175eb1cc8347512ca327b191619fc32ed65efaab26d8"
}
「エラー応答」を参照してください。 |
OAuth アイデンティティプロバイダを使用したソリューションへのログイン
共有ソリューションにログインするには、HTTP POST メソッドを使用して共有ソリューションの名前を auth
URL で指定します。
アカウント名とパスワードが認証されると、コードはソリューションへの接続を定義するアクセストークンを受け取ります。
HTTP メソッド | POST |
---|---|
URL | /fmi/rest/api/auth/solution solution – 共有データベースの名前 |
HTTP ヘッダ | Content/Type: application/json X-FM-Data-Login-Type: oauth |
引数 | 認証用のコールバック URL が含まれる OAuth リクエスト ID、OAuth アイデンティティプロバイダから返された OAuth 識別子、ログイン後に切り替えるレイアウト。 データはすべて JSON 形式である必要があります。 例: {
"oAuthRequestId":"E65B98CC17429CO643A31119F",
"oAuthIdentifier":"B164A4629A776E5177445DR223",
"layout":"連絡先"
} |
応答 | アクセストークン、現在のレイアウト、およびエラーコード 0。 例: {
"errorCode": "0",
"layout": "連絡先",
"token": "fdde35fa175eb1cc8621782fd327b191619fc32ed65efaab26d8"
}
「エラー応答」を参照してください。 |
OAuth 引数を JSON 形式で取得するには:
-
次の URL と HTTP GET メソッドを使用することにより、サポートされている OAuth プロバイダの一覧を取得します:
https://<ホスト>/fmws/oauthproviderinfo
<ホスト> は FileMaker Server 展開内のマスタマシンの IP アドレスまたはドメイン名です。 一覧が JSON 形式で返されます。
- サポートされている OAuth プロバイダを選択してソリューションの追跡 ID を取得します。
-
次の URL と HTTP GET メソッドを使用します:
http://<ホスト>/oauth/getoauthurl?trackingID=追跡 ID&provider=OAuth プロバイダ&address=127.0.0.1&X-FMS-OAuth-AuthType=2
<ホスト> は FileMaker Server 展開内のマスタマシンの IP アドレスまたはドメイン名、「追跡 ID」は開発者がソリューション用に生成した追跡 ID、「OAuth プロバイダ」は選択した 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 データの応答ヘッダを読み取ります。 この応答ヘッダにはログインに使用する OAuth リクエスト ID が含まれています。
- X-FMS-Return-URL データの応答ヘッダを読み取ります。 この引数で返された URL を呼び出すことによって、ユーザが OAuth プロバイダから認証を受けられるようになります。
- OAuth プロバイダから返される「識別子」はログインに使用する OAuth 識別子の引数です。
FileMaker Pro ヘルプの「OAuth アイデンティティプロバイダで認証するアカウントの作成」を参照してください。
ソリューションからのログアウト
コードによる共有ソリューションへのアクセスが完了したら、HTTP DELETE メソッドを使用して共有ソリューションの名前を auth
URL で指定します。
リクエストヘッダでセッショントークンが送信されます。
コードが共有ソリューションからログアウトしていない場合、アクセストークンを指定した最後の呼び出しから 15 分後に FileMaker Data API セッションがタイムアウトになると、そのトークンが無効になります。
HTTP メソッド | DELETE |
---|---|
URL | /fmi/rest/api/auth/solution solution – 共有データベースの名前 |
HTTP ヘッダ | FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | なし |
応答 | エラーコード 0。 例: {
"errorCode": "0"
}
「エラー応答」を参照してください。 |
レコードを操作する呼び出し
レコードの作成
レコードを作成するには、HTTP POST メソッドを使用してソリューション名とレイアウトを record
URL で指定します。
HTTP メソッド | POST |
---|---|
URL | /fmi/rest/api/record/solution/layout solution – 共有データベースの名前 |
HTTP ヘッダ | Content/Type: application/json FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | 目的のレイアウト内にあるフィールドに値を指定するフィールド/値ペアが含まれた JSON 形式のレコードデータ。 例: {"data":
{
"フィールド 1": "値 1",
"フィールド 2": "値 2",
"繰り返しフィールド (1)" : "フィールド値",
"注文::注文日.0":"12/22/2015"
}
}
メモ: 各フィールドのデフォルト値が空のレコードを作成するには、引数として空のデータオブジェクトを JSON 形式で指定します。 例: {"data":
{
}
} |
応答 | エラーコード 0 および作成されたレコードのレコード ID。 例: {
"errorCode": "0",
"recordId": "25"
}
「エラー応答」を参照してください。 |
メモ
- FileMaker Data API を使用してレコードを作成する際はフィールドの入力値の制限が強制されます。 データがフィールドの入力値の制限を満たしていない場合、エラーメッセージが返されてレコードは作成されません。
-
関連レコードを作成するには、関連レコードのレコード ID を省略するか、または関連レコードのレコード ID として値 0 (ゼロ) を使用し、その後に新規フィールド値を記述します。
たとえば、関連レコードを作成するには、次のいずれかを使用します:
"注文::注文日" : "12/22/2017" "注文::注文日.0" : "12/22/2017"
関連レコードは、レコードの作成の呼び出しごとに 1 つのみ作成できます。
レコードの編集
レコードを編集するには、HTTP PUT メソッドを使用してソリューション名、レイアウト、およびレコード ID を record
URL で指定します。
HTTP メソッド | PUT |
---|---|
URL | /fmi/rest/api/record/solution/layout/recordid solution – 共有データベースの名前 |
HTTP ヘッダ | Content/Type: application/json FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | 更新するフィールド/値ペアが含まれた JSON 形式のレコードデータ。 このデータでレイアウト上にある関連レコードまたはポータルを指定することもできます。 指定したフィールドのみが更新されます。レコード内の他のフィールドは変更されません。 データ値として「{}」を指定した場合、目的のレコードは更新されません。 オプションの引数: 修正 ID。 修正 ID を指定すると、現在のバージョンのレコードを編集することができます。 修正 ID の値がデータベース内の現在の修正 ID の値と一致しない場合、レコードは変更されません。 例: {"data":
{
"名": "Bob",
"姓": "Smith",
"機器 (2)" : "PC",
"注文::注文日.2":"12/20/2017",
"注文::注文日.0":"12/22/2017", // recordId が 0 の「注文」関連レコードを作成
"deleteRelated": "注文.3" // "deleteRelated" 文字列を使用して「注文」関連レコードを削除
},
modId: "3"
} |
応答 | エラーコード 0 および編集されたレコードのレコード ID。 例: {
"errorCode": "0",
"recordId": "53"
}
「エラー応答」を参照してください。 |
メモ
- FileMaker Data API を使用してレコードを編集する際はフィールドの入力値の制限が強制されます。 データがフィールドの入力値の制限を満たしていない場合、エラーメッセージが返されてレコードは更新されません。
-
関連レコードを作成するには、関連レコードのレコード ID を省略するか、または関連レコードのレコード ID として値 0 (ゼロ) を使用し、その後に新規フィールド値を記述します。
たとえば、関連レコードを作成するには、次のいずれかを使用します:
"注文::注文日" : "12/22/2017" "注文::注文日.0" : "12/22/2017"
関連レコードは、レコードの編集の呼び出しごとに 1 つのみ作成できます。 -
関連レコードを削除するには、文字列「deleteRelated」を使用してその後に削除する関連レコードを記述します。
例:
"deleteRelated" : "注文.3"
関連レコードは、レコードの編集の呼び出しごとに 1 つのみ削除できます。
レコードの削除
レコードを削除するには、HTTP DELETE メソッドを使用してソリューション名、レイアウト、およびレコード ID を record
URL で指定します。
HTTP メソッド | DELETE |
---|---|
URL | /fmi/rest/api/record/solution/layout/recordid solution – 共有データベースの名前 |
HTTP ヘッダ | FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | なし |
応答 | エラーコード 0。 例: {
"errorCode": "0"
}
「エラー応答」を参照してください。 |
単一のレコードの取得
単一のレコードを取得するには、HTTP GET メソッドを使用してソリューション名、レイアウト、およびレコード ID を record
URL で指定します。
ポータル情報を指定して返される関連レコードの数を制限することもできます。
HTTP メソッド | GET |
---|---|
URL | 形式 1:
/fmi/rest/api/record/solution/layout/recordid solution – 共有データベースの名前 portal キーワードについて: URL の portal 部分はオプションです。 レイアウトに複数のポータルが含まれている場合は、パフォーマンスを向上させるためにポータル名を指定します。 portal 部分を省略した場合、呼び出しによってレイアウト上のすべてのポータルにあるすべての関連レコードが返されます。 |
HTTP ヘッダ | FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | なし |
応答 | エラーコード 0 および JSON 形式のレコードデータ。 例: {
"errorCode": "0",
"record": "{...}"
}
「エラー応答」を参照してください。 |
メモ
- 返される関連レコードの数を制限するために、FileMaker Data API では、[ポータル設定] ダイアログボックスの [垂直スクロールを許可] オプションがサポートされます。 このオプションを選択した場合、FileMaker Data API はポータルから最初の 50 行を返します。 このオプションを選択しない場合、FileMaker Data API は [行数] オプションに指定された行数を返します。
- ポータル行をスクロールするには、
offset.<ポータル名>
およびrange.<ポータル名>
という構文を使用します。<ポータル名>
は FileMaker Pro のインスペクタでポータルに指定されている値です。 ポータル行のオフセット値と範囲値を省略した場合、デフォルトのオフセット値 1 とデフォルトの範囲値 50 が使用されます。
レコードの範囲の取得
レコードの範囲を取得するには、HTTP GET メソッドを使用してソリューション名、レイアウト、および開始レコードとレコード数を指定する追加情報を record
URL で指定します。
オプションでレコードのソート順を指定できます。
ポータル情報を指定して返される関連レコードの数を制限することもできます。
HTTP メソッド | GET |
---|---|
URL | 形式 1:
/fmi/rest/api/record/solution/layout?offset=開始レコード&range=レコード数 solution – 共有データベースの名前 sort の指定では情報を JSON 形式で指定する必要があります。 フィールド名はレコードのソート基準として使用するフィールドの名前です。 複数のフィールド名を指定することができます。 ソート順には「ascend」または「descend」キーワードを指定するか、あるいは「値一覧名」に値一覧の名前を指定します。 portal キーワードについて: URL の portal 部分はオプションです。 レイアウトに複数のポータルが含まれている場合は、パフォーマンスを向上させるためにポータル名を指定することができます。 portal 部分を省略した場合、呼び出しによってレイアウト上のすべてのポータルにあるすべての関連レコードが返されます。 |
HTTP ヘッダ | FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | なし |
応答 | エラーコード 0 および JSON 形式のレコードデータの範囲。 例: {
"errorCode": "0",
"records": "[...]"
}
「エラー応答」を参照してください。 |
メモ
- offset と range の値を省略した場合、デフォルトのオフセット値 1 とデフォルトの範囲値 100 が使用されます:
offset=1&range=100
- ソート順の値を省略した場合、デフォルトは次のようになります。
&sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }]
- 返される関連レコードの数を制限するために、FileMaker Data API では、[ポータル設定] ダイアログボックスの [垂直スクロールを許可] オプションがサポートされます。 このオプションを選択した場合、FileMaker Data API はポータルから最初の 50 行を返します。 このオプションを選択しない場合、FileMaker Data API は [行数] オプションに指定された行数を返します。
- ポータル行をスクロールするには、
offset.<ポータル名>
およびrange.<ポータル名>
という構文を使用します。<ポータル名>
は FileMaker Pro のインスペクタでポータルに指定されている値です。 ポータル行のオフセット値と範囲値を省略した場合、デフォルトのオフセット値 1 とデフォルトの範囲値 50 が使用されます。
検索を実行する呼び出し
検索を実行するには、HTTP POST メソッドを使用してソリューション名およびレイアウトと、クエリーフィールド、クエリー条件、ソート順、開始レコード、およびレコード数を指定する追加情報を find
URL で指定します。
ポータル情報を指定して関連レコードを検索することもできます。
HTTP メソッド | POST |
---|---|
URL | /fmi/rest/api/find/solution/layout solution – 共有データベースの名前 |
HTTP ヘッダ | FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | フィールドおよび検索条件を指定する JSON 形式のクエリー。 除外リクエスト、ソート順、開始レコード (オフセット)、レコード数 (範囲)、および返される関連レコード数を制限するためのポータルを指定するオプション引数。 例: {
"query":[
{"Group": "=外科医", "勤務先の都道府県" : "東京都"},
{"Group": "=外科医", "勤務先の市区町村" : "港区", "omit" : "true"}],
"sort":[
{"fieldName": "勤務先の都道府県","sortOrder": "ascend"},
{"fieldName": "名", "sortOrder": "ascend"} ]
}
オフセット、範囲、およびポータルの使用例: {
"query":[
{"Group": "=外科医", "勤務先の都道府県" : "東京都"},
{"Group": "=外科医", "勤務先の市区町村" : "港区", "omit" : "true"}],
"portal": ["ポータル 1","ポータル 2"],
"range": "10",
"offset": "1",
"offset.Portal1": "1",
"range.Portal1": "5"
} |
応答 | エラーコード 0 および対象レコードの JSON 表現。 例: {
"errorCode": "0",
"data": [レコード 1, レコード 2, ...]
}
「エラー応答」を参照してください。 |
メモ
- 関連レコードが多いソリューションでは、ポータルレコードのクエリーを実行してソートすると時間がかかる可能性があります。 関連セットで表示するレコードと行の数を制限するには、オフセット引数および範囲引数を指定します。
- 検索条件としてグローバルフィールドを指定することはできません。 検索条件でグローバルフィールドを指定すると、エラーメッセージが返されます。 代わりに、検索条件の前にグローバルフィールドの値を設定してください。 「グローバルフィールドの値を設定する呼び出し」を参照してください。
グローバルフィールドの値を設定する呼び出し
グローバルフィールドの値を設定するには、HTTP PUT メソッドを使用してソリューション名とレイアウトを global
URL で指定します。
HTTP メソッド | PUT |
---|---|
URL | /fmi/rest/api/global/solution/layout solution – 共有データベースの名前 |
HTTP ヘッダ | FM-Data-token、ソリューションにログインした呼び出しに返されたアクセストークンを指定 |
引数 | 設定するグローバルフィールドを指定するフィールド/値ペアが含まれる JSON オブジェクト。 例: { "globalFields":
{
"gCompany":"FileMaker",
"gCode":"95054"
}
} |
応答 | エラーコード 0。 例: {
"errorCode": "0"
}
「エラー応答」を参照してください。 |
エラー応答
エラーが発生した場合、FileMaker Data API は一般に HTTP 400 番台のステータスコードと追加情報を JSON オブジェクトで返します。
HTTP ステータスコード | HTTP カテゴリ | JSON エラー形式 | 説明 |
---|---|---|---|
400 | 不正なリクエスト | {
"errorMessage": "エラーの詳細"
} |
クライアントエラーのためサーバーがリクエストを処理できない場合に発生します。 |
401 | 権限がありません | {
"errorMessage": "Unauthorized"
} |
クライアントが API にアクセスする権限がない場合に発生します。 共有ソリューションへのログイン試行中にこのエラーが起きた場合、指定されたユーザアカウントまたはパスワードに問題があります。 他の呼び出しでこのエラーが起きた場合、アクセストークンが指定されていないか、または無効です。 |
404 | 見つかりません | {
"errorMessage": "Not found"
} |
呼び出しが無効な URL スキーマの URL を使用した場合に発生します。 指定した URL に構文エラーがないか確認してください。 |
415 | サポートされていないメディアタイプ | {
"errorMessage": "Unsupported Media Type"
} |
「Content/Type: application/json」ヘッダが指定されていないか、または「application/json」タイプの代わりに別のコンテンツタイプが指定された場合に発生します。 |
477 | FileMaker サービスエラー | {
"errorMessage": "FileMaker エラーメッセージ",
"errorCode": "FileMaker エラーコード"
} |
FileMaker のエラーメッセージとエラーコードが含まれます。 FileMaker Pro ヘルプの「FileMaker エラーコード」を参照してください。 |
メモ
- FileMaker Data API エンジンが実行されていないか、またはアクセスできない場合、エラーメッセージなしでステータスコード 0 (ゼロ) が返されることがあります。
- 返されるその他の HTTP ステータスコードの詳細については、www.w3.org を参照してください。
FileMaker Data API ソリューションの共有、テスト、監視
FileMaker Data API ソリューションの共有
- 「FileMaker Data API アクセス用のデータベースの準備」に記載されているすべての手順を完了します。
- FileMaker Data API アクセスが FileMaker Server Admin Console で有効に設定されて正しく構成されていることを確認します。 FileMaker Server ヘルプを参照してください。
- Web サーバー、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 ログファイルの表示を実行できます。
目的 | 用途 |
---|---|
FileMaker Data API エンジンを起動または停止する | Admin Console の [ステータス] パネルまたは CLI コマンド。 FileMaker Server ヘルプの「FileMaker Server コンポーネントの起動または停止」および「コマンドラインインターフェースの使用」を参照してください。 |
FileMaker Data API 設定を変更する | Admin Console の [Web 公開] > [FileMaker Data API] タブ。 このタブで、FileMaker Data API の使用の有効化、FileMaker Data API 呼び出しのログの有効化、FileMaker Data API ログファイルの最大サイズの設定、およびログファイルに書き込まれるメッセージのログレベルの設定を行います。 FileMaker Server ヘルプの「FileMaker Data API 設定」を参照してください。 |
FileMaker Data API クライアントを監視する | Admin Console の [アクティビティ] > [クライアント] タブ。 このタブには、クライアントの詳細とアクセスされているソリューションの詳細が表示されます。 FileMaker Server ヘルプの「クライアントの管理」を参照してください。 このタブから FileMaker Data API クライアントを切断できますが、クライアントにメッセージを送信することはできません。 FileMaker Data API クライアントがソリューションに接続している間、クライアントに関する使用状況データが Admin Console の [使用状況] > [クライアント] タブに表示されます。 FileMaker Server ヘルプの「クライアントの使用状況の表示」を参照してください。 |
FileMaker Data API 呼び出しの使用を追跡する | Admin Console の [Web 公開] > [FileMaker Data API] タブ。 このタブには、FileMaker Server ライセンスで許可されている FileMaker Data API 呼び出し数、今月使用された呼び出し数、および先月使用された呼び出し数が表示されます。 呼び出し数の制限に近づいた場合には呼び出しを追加購入することもできます。 FileMaker Server ヘルプの「FileMaker Data API 設定」を参照してください。 |
FileMaker Data API のログを表示する | Admin Console の [ログビューア] タブ。 FileMaker Data API コンポーネントによって FileMaker Data API を使用して共有ソリューションにアクセスするクライアントに関連するログ情報が生成されます。 FileMaker Server ヘルプの「FileMaker Data API のログ」を参照してください。 |
FileMaker Data API と Tableau との統合
Tableau との統合について
FileMaker Server には、JSON 形式の REST API 呼び出しを使用できるサンプル実装である Tableau Web データコネクタが含まれています。 Tableau Web データコネクタを使用して FileMaker Server と Tableau Desktop 間の接続を定義します。 この接続では FileMaker Data API を使用して共有されている FileMaker ソリューションから Tableau Desktop へデータをインポートします。
Tableau Web データコネクタの必要条件
- Tableau Desktop、最小バージョン 9.1、Windows または Mac 用。
- インポートするデータが含まれているパスワードで保護された FileMaker Pro データベース。 データベースは FileMaker Server で共有されている必要があります。
-
有効な REST API エンドポイント。 FileMaker Server の場合、エンドポイントは Web サービスに必要な情報を提供する HTML 接続ポイントです。 エンドポイントの形式は次のとおりです:
https://<ホスト名>/fmi/rest/tableau/fm_connector.html
<ホスト名>
は FileMaker Server の完全修飾ホスト名です。例:
https://myserver.mycompany.com/fmi/rest/tableau/fm_connector.html
- FileMaker Server 上の有効なカスタム SSL 証明書。 Tableau Web データコネクタでは、有効なカスタム SSL 証明書がないと FileMaker Server からデータをインポートできません。
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 ポータルからのデータ。 関連レコードからデータをインポートするには、関連テーブルに基づく FileMaker Pro レイアウトを作成するか、または別の FileMaker Pro テーブルから Tableau へデータをインポートしてから Tableau でテーブルを結合します。
- 繰り返しフィールドの [繰り返しを表示] 設定の表示に複数の値が含まれているフィールドの繰り返し。単一の繰り返しはサポートされます。
- 数字フィールドの数値以外の値。Tableau が数字フィールドで数値以外の値を検出した場合、そのデータはインポートされません。
FileMaker Pro でフィールド名として予約されている単語を使用しないでください。
Tableau Desktop でのデータ接続の設定
- Tableau Desktop の [接続] (画面の左側) で、[その他のサーバー...] > [Web データコネクタ] を選択します。
- FileMaker Server エンドポイントの URL を入力します:
https://<ホスト名>/fmi/rest/tableau/fm_connector.html
<ホスト名>
は FileMaker Server の完全修飾ホスト名です。 -
[FileMaker ファイルからのデータのインポート] ダイアログボックスで次の操作を行います:
-
次の情報を入力するか OAuth アイデンティティプロバイダを使用して FileMaker Pro ソリューションにサインインします。
- [ソースデータベース名]: FileMaker Pro ソリューションの名前
- [ソースレイアウト名]: FileMaker Pro レイアウトの名前
- [アカウント名]: fmrest アクセス権のある FileMaker Pro アカウントの名前
- [パスワード]: FileMaker Pro アカウントのパスワード
- [増分更新を有効にする] を選択して増分更新を有効にします。
-
- [FileMaker データのインポート] をクリックします。
Tableau によりデータがインポートされます。 処理時間はインポートするレコード数、サーバーの負荷、およびネットワークスループットによって変わります。 Tableau によって FileMaker Pro フィールド名およびデータがディメンションおよびメジャーにマッピングされます。通常、文字列データはディメンションにマッピングされ、数値データはメジャーにマッピングされます。 マッピングはインポート中に自動的に行われますが、カスタマイズすることもできます。
メモ
-
[ソースレイアウト名] を指定する際はレイアウト名が固有であることを確認してください。 データベースに同じ名前のレイアウトが 2 つある場合、Tableau データ接続ではその 2 つを区別できません。 Tableau には名前が 1 つのみ表示され、それが必要としていたレイアウトではない可能性もあります。
-
新規レコードのみをインポートするには、[増分更新を有効にする] を使用します。
- 増分更新を有効にして FileMaker データをインポートした後に、Tableau の [シート] タブを選択してワークシートに移動します。
- [データ] > [FM: ソリューション名 / レイアウト名] > [抽出] > [更新 (増分)] を選択します。
- [データソース] タブを選択します。
- [更新] をクリックして新規レコードを表示します。
- 増分更新を有効にしても、共有されている FileMaker データベースと Tableau 間に継続的なライブ接続は確立されません。 増分更新を手動で実行する必要があります。
- 増分更新では、新規レコードのみがインポートされます。 変更または削除された FileMaker Pro レコードは更新されません。 変更データを取得するか削除されたレコードを取り除くには、Tableau でワークブックを新規作成してデータを再インポートする必要があります。
- 増分更新では、-recordId という名前のフィールドが作成されます。 このフィールドを変更すると、増分更新を実行できなくなる可能性があります。
- Tableau で、インポートされたスキーマおよびデータを変更できます。 ただし、Tableau でスキーマまたはデータを変更しても、これらの変更は FileMaker Pro ファイルに送信されません。
- FileMaker Pro ファイルでスキーマを変更した場合は、Tableau でワークブックを新規作成してデータを再インポートする必要があります。
- Tableau Desktop データベースは、Tableau Server for Windows 上で共有することができます。
- Tableau ワークブックを閉じてから再度開くと、増分インポートが動作しなくなります。
- Tableau へのデータ接続が確立されると、次の状況を考慮して、ワークブックが閉じられるまで FileMaker Web データコネクタによってユーザアカウントとパスワードがキャッシュされます:
- Tableau に接続している間に FileMaker セッションがタイムアウトになった場合、FileMaker Web データコネクタは FileMaker Server へのユーザの再接続を試行します。
- Tableau 接続が期限切れになった場合、Tableau ワークブックが開いている限り、FileMaker Web データコネクタは FileMaker Server への再接続を試行します。
- ワークブックを閉じてから再度開いた場合は、最初のデータインポート時にアカウント名とパスワードを再入力する必要があります。
- Tableau の [データソース] ページには、最大 1,000,000 (100 万) 行が表示されます。これより多くのレコードがインポートされた場合も同様です。