执行 FileMaker Data API

执行 FileMaker Data API 请求。

另请参阅

使用脚本自动执行任务

选项

“选择全部内容”会替换字段或变量的内容。如果未选择此选项：
- 对于字段，将仅替换活动字段的选定部分，或在插入点处插入数据。默认插入点位于字段数据的结尾。
- 对于没有容器数据的变量，将在变量当前值的结尾插入数据。对于具有容器数据的变量，将替换变量内容。
“目标”指定要在其中插入结果的字段或要设置的变量。如果变量不存在，则此脚本步骤将创建一个变量（请参阅使用变量）。
“请求”是将请求指定为文本的计算。文本是使用下述格式的 JSON 对象。

兼容性

产品	是否支持
FileMaker Pro	是
FileMaker Go	是
FileMaker WebDirect	是
FileMaker Server	是
FileMaker Cloud	是
FileMaker Data API	是
自定义 Web 发布	是

原始版本

19.0

说明

FileMaker Data API 是一种 REST API，可作为 FileMaker Server 和 FileMaker Cloud 的 Web 服务。Web 应用程序可以使用此 API 发送请求以及从托管的 FileMaker Pro 文件接收 JSON 格式的数据。

此脚本步骤使用与 FileMaker 主机上的 FileMaker Data API 相同的底层功能，允许任何 FileMaker 产品执行的脚本请求当前文件中的数据，无论是否托管，都接收 JSON 格式的数据。此脚本步骤不会使用 FileMaker Data API 对主机进行 Web 服务调用，也不取决于 API 是否在主机上启用。此脚本步骤与 FileMaker Data API 之间的相似之处主要是返回数据的 JSON 格式相同。请求是简单的 JSON 对象，而不是 FileMaker Data API 使用 FileMaker 主机的 web 服务所需的 URL、标头和请求的组合。“目标”中返回的结果使用在通过 FileMaker Data API 从主机请求时相同的 JSON 格式。

请求格式

此脚本步骤支持“请求”选项指定的 JSON 对象中的以下键值对。如果其中一个键在请求中未指定，将使用默认值。

键	默认值	说明
`action`	`"read"`	`read`、`metaData`、`create`、`update`、`delete` 和 `duplicate` 是支持的值。使用 `metaData` 检索有关表格和布局的信息。使用其他值对记录数据采取行动。
`version`	`"v1"`	`v1`、`v2` 和 `vLatest` 是支持的值。行为和生成的结果根据 API 版本而不同。
`layouts`		布局名称。
`tables`		表格关系实例的名称。表格关系实例 `metaData` 操作所必需。作用类似 `layouts` 键。如果指定了表格关系实例，将返回该表格的元数据。如果未指定名称，将返回表格关系实例列表。
`查询`	所有记录	JSON 对象数组，每个对象指定一个字段和查找条件。
`recordId`		记录的唯一 ID 号。您无法同时指定 `query` 和 `recordId` 键。
`sort`		指定当前布局表格中记录排序顺序的 JSON 对象。
`offset`	`1`	当前布局表格的记录范围中第一条记录的记录编号。
`limit`	`100`	应从当前布局表格返回的最大记录数。
`layout.response`	来自 `layouts` 的值	要在不同布局的上下文中检索数据，请指定布局名称。
`入口`	所有入口	用于指定入口的 JSON 对象。
`offset.portal-name`	`1`	相关记录范围中第一条入口记录的记录编号。对于 `portal-name`，必须指定入口的对象名称，如果存在，则指定相关表格名称。
`limit.portal-name`	50	应返回的最大相关记录数。对于 `portal-name`，必须指定入口的对象名称，如果存在，则指定相关表格名称。
`fieldData`		指定要创建或更新的记录数据的 JSON 对象。
`portalData`		指定要创建或更新的相关记录数据的 JSON 对象。
`modId`		（可选）对于更新操作，要更新的记录的修改 ID。如果它与记录的当前 modId 不匹配，则记录将不会被修改。
`"选项": {"entrymode":"值"}`	`"user"`	（可选）在写入数据时，此脚本步骤忽略是否选择了字段的“允许用户在数据输入期间覆盖”选项，而是使用 `entrymode` 值。对于`值`，使用： `script`：忽略字段的数据验证要求 `user`：遵循字段的数据验证要求请参阅定义字段验证。
`"选项": {"prohibitmode":"值"}`	`"user"`	（可选）在写入数据时，此脚本步骤会忽略字段的“在数据输入期间禁止修改值”选项是否被选中，而是使用 `prohibitmode` 值。对于`值`，使用： `script`：忽略字段的自动数据输入要求 `user`：遵循字段的自动数据输入要求请参阅定义自动数据输入。

有关上述密钥的更多信息，请参阅 FileMaker Data API 指南中的“处理记录”以及“获取元数据”和“执行查找请求”下的主题。

以下键被忽略：

databases 被忽略，因为数据库始终属于脚本在其中运行的窗口。
Authorization 被忽略，因为脚本的权限是当前用户的权限，或者，如果已对当前脚本授予完全访问权限，则其权限为完全访问权限。
Content-Type 被忽略，因为请求必须为 JSON 格式。
script 以及以 script. 开头的任何键被忽略。要执行另一个脚本，请改为使用执行脚本脚本步骤。

错误处理

Target 中的 JSON 结果至少包含消息键，其中具有包含消息和代码键的对象。代码值是 FileMaker 错误代码中定义的值。大多数消息和代码值与 FileMaker Data API 作为 FileMaker 主机上的网络服务返回的值相同。某些其他错误是此脚本步骤才会产生的，帮助在解析请求选项时识别问题。这些其他错误使用代码值 3、1708 和 1710，但使用许多不同的消息值来提供错误的详情信息。

Get (上一个错误) 和 Get (上一个错误详情) 函数分别返回与代码和消息键相同的值。Get (上一个错误位置) 返回脚本中错误发生的位置。

注释

此脚本步骤在自己的会话中执行，与任何窗口或可能正在运行的脚本的上下文无关，包括执行此脚本步骤的脚本。因此，使用此脚本步骤就像正在通过网络对主机进行 FileMaker Data API 调用一样。因此，在执行此脚本步骤时，脚本触发器和任何错误报告对话框都被禁用。
如果文件由 FileMaker Server 或 FileMaker Cloud 托管，则返回的容器字段值是可用于提取字段内容的 URL。如果文件在本地打开，则只返回容器字段中文件的名称。

示例 1

不为 tables 键指定值，从而对所有表格关系实例返回元数据。在这种情况下，有一个来源（或基础）表格 (Products) 和两个表格关系实例（Products 和 Products_InStock）。此示例使用 JSONSetElement函数在请求选项中创建 JSON 对象。

复制

执行 FileMaker Data API [ 选择 ; 目标: $$result ; JSONSetElement ( "{}" ; [ "action" ; "metaData" ; JSONString ] ; [ "tables" ; "" ; JSONString ] ) ] 设置变量 [ $$result ; JSONFormatElements ( $$result ) ]

全局变量 $$result 中返回的 JSON 数据使用此格式。

复制

{
    "messages" : 
    [
        {
            "code" : "0",
            "message" : "OK"
        }
    ],
    "response" : 
    {
        "tables" : 
        [
            {
                "baseTable" : "Products",
                "name" : "Products"
            },
            {
                "baseTable" : "Products",
                "name" : "Products_InStock"
            }
        ]
    }
}

示例 2

根据产品布局，返回产品布局相关表格中的第一条记录。

复制

执行 FileMaker Data API [ 选择 ; 目标: $$result ; JSONSetElement ( "{}" ; [ "layouts" ; "Products" ; JSONString ] ; [ "limit" ; 1 ; JSONNumber ] ) ] 设置变量 [ $$result ; JSONFormatElements ( $$result ) ]

全局变量 $$result 中返回的 JSON 数据使用此格式。

复制

{
    "messages" : 
    [
        {
            "code" : "0",
            "message" : "OK"
        }
    ],
    "response" : 
    {
        "data" : 
        [
            {
                "fieldData" : 
                {
                    "ID" : "FB1",
                    "Name" : "Donuts",
                    "Stock" : 43
                },
                "modId" : "6",
                "portalData" : {},
                "recordId" : "1"
            }
        ],
        "dataInfo" : 
        {
            "database" : "Favorite Bakery",
            "foundCount" : 3,
            "layout" : "Products",
            "returnedCount" : 1,
            "table" : "Products",
            "totalRecordCount" : 3
        }
    }
}

示例 3

根据 Products 布局，查找其中 Stock 字段小于 40 的记录，并以 Stock 字段的降序排序返回找到的集。

复制

执行 FileMaker Data API [ 选择 ; 目标: $$result ; JSONSetElement ( "{}" ; [ "layouts" ; "Products" ; JSONString ] ; [ "query" ; "[ { \"Stock\":\"<40\" } ]" ; JSONArray ] ; [ "sort" ; "[ { \"fieldName\":\"Stock\" , \"sortOrder\":\"descend\" } ]" ; JSONArray ] ) ] 设置变量 [ $$result ; JSONFormatElements ( $$result ) ]

全局变量 $$result 中返回的 JSON 数据使用此格式。

复制

{
    "messages" : 
    [
        {
            "code" : "0",
            "message" : "OK"
        }
    ],
    "response" : 
    {
        "data" : 
        [
            {
                "fieldData" : 
                {
                    "ID" : "FB3",
                    "Name" : "Baguette",
                    "Stock" : 34
                },
                "modId" : "1",
                "portalData" : {},
                "recordId" : "7"
            },
            {
                "fieldData" : 
                {
                    "ID" : "FB2",
                    "Name" : "Chocolate Cake",
                    "Stock" : 23
                },
                "modId" : "1",
                "portalData" : {},
                "recordId" : "6"
            }
        ],
        "dataInfo" : 
        {
            "database" : "Favorite Bakery",
            "foundCount" : 2,
            "layout" : "Products",
            "returnedCount" : 2,
            "table" : "Products",
            "totalRecordCount" : 3
        }
    }
}

示例 4

根据产品布局，返回与产品布局相关的表中的第一条记录，如果有入口行，将在跳过第一个 2 后返回前 2 条记录。

复制

执行 FileMaker Data API [ 选择 ; 目标: $$result ; 
JSONSetElement ( "{}" ; 
    [ "layouts" ; "Products" ; JSONString ] ;
    [ "limit" ; 1 ; JSONNumber ] ;
    [ "['limit.RelatedProducts']" ; 2; JSONNumber ] ; 
    [ "['offset.RelatedProducts']" ; 2 ; JSONNumber ]
) ]
设置变量 [ $$result ; JSONFormatElements ( $$result ) ]

全局变量 $$result 中返回的 JSON 数据使用此格式。

复制

{
    "messages" : 
    [
        {
            "code" : "0",
            "message" : "OK"
        }
    ],
    "response" : 
    {
        "data" : 
        [
            {
                "fieldData" : 
                {
                    "ID" : "FB1",
                    "Name" : "Donuts",
                    "Stock" : 43
                },
                "modId" : "6",
                "portalData" : {
                    "RelatedProducts" :
                    [
                        {
                            "ID" : "FB4",
                            "Name" : "Donut Holes",
                            "Stock" : 53
                        },
                        {
                            "ID" : "FB5",
                            "Name" : "Short Cake",
                            "Stock" : 15
                        }
                    ]
                },
                "recordId" : "1"
            }
        ],
        "dataInfo" : 
        {
            "database" : "Favorite Bakery",
            "foundCount" : 3,
            "layout" : "Products",
            "returnedCount" : 1,
            "table" : "Products",
            "totalRecordCount" : 6
        }
    }
}

示例 5

基于产品布局，修改 recordId 指定的记录，更新 Stock 和 Name 字段的值。

复制

执行 FileMaker Data API [ 选择 ; 目标: $$result ; 
JSONSetElement ( "{}" ; 
    [ "action" ; "update" ; JSONString ] ;
    [ "layouts" ; "Products" ; JSONString ] ;
    [ "recordId" ; "4" ; JSONString ] ;
    [ "fieldData" ; "{ \"Stock\" : 14 , 
       \"Name\" : \"Vanilla Cake, Large\" }" ; JSONObject ] 
) ]
设置变量 [ $$result ; JSONFormatElements ( $$result ) ]

全局变量 $$result 中返回的 JSON 数据使用此格式。

复制

{
    "messages" : 
    [
        {
            "code" : "0",
            "message" : "OK"
        }
    ],
    "response" : 
    {
        "modId" : "6"
    }
}

如果 recordId 指定的记录不存在，Get(上一个错误) 将返回 101，Get(上一个错误详情) 将返回“记录缺失”，这与 $$result 中的代码和消息相同。

示例 6

基于产品布局，创建记录并设置库存、ID 和名称字段的值。由于 ID 字段设置为自动输入序列号，并且启用了“在数据输入期间禁止修改值”选项，因此在 options 对象中将 prohibitmode 键设置为 script 会覆盖自动输入要求，并按指定设置 ID 字段。

复制

执行 FileMaker Data API [ 选择 ; 目标: $$result ; 
        JSONSetElement ( "{}" ; 
        [ "action" ; "create" ; JSONString ] ;
        [ "layouts" ; "Products" ; JSONString ] ;
        [ "options" ; "{ \"prohibitmode\" : \"script\" }" ; JSONObject ] ;
        [ "fieldData" ; "{ \"Stock\" : 14 , 
           \"ID\" : \"FB42\" ,
           \"Name\" : \"Croissants\" }" ; JSONObject ] 
        ) ]
        设置变量 [ $$result ; JSONFormatElements ( $$result ) ]

全局变量 $$result 中返回的 JSON 数据使用此格式。

复制

{
        "messages" : 
        [
           {
               "code" : "0",
               "message" : "OK"
           }
        ],
        "response" : 
        {
           "modId" : "0",
           "recordId" : "7"
        }
        }

如果 ID 字段的验证设置也要求唯一值，并且 ID 值为“FB42”的记录已经存在，那么 Get(上一个错误) 将返回 504，Get(上一个错误详情) 将返回“字段中的值不是唯一的，如验证条目选项中的要求”，这与 $$result 中的 code 和 message 相同。

执行 FileMaker Data API

另请参阅

选项

兼容性

原始版本

说明

请求格式

错误处理

注释

示例 1

示例 2

示例 3

示例 4

示例 5

示例 6

相关主题