App Maker Server API

App

此类允许服务器脚本访问数据并检查权限，它提供应用制作工具专有的其他功能。

    var userRoles = app.getActiveUserRoles();
    if (userRoles.indexOf(app.roles.Admins) >= 0) {
      // Create admin-only application settings record.
      var settings = app.models.Settings.newRecord();
      app.saveRecords([settings]);
    }

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
roles string[string] 该应用中定义的所有用户角色。


    if (userRoles.indexOf(app.roles.Admins) < 0) {
      throw 'Access denied';
    }
models Model[string] 该应用中定义的所有数据模型。


    var record = app.models.Person.newRecord();
    app.saveRecords([record]);
metadata Metadata 该应用中定义的所有元数据。


    var displayField = app.metadata.models.model1.displayField;
ManagedError function(message: String) 显示自定义错误消息。


    throw new app.ManagedError("Custom message shown to app users");
transaction Transaction 控制 Cloud SQL 模型中的事务。


    app.transaction.cloudSql.start(app.transaction.cloudSql.isolation.REPEATABLE_READ);

方法

名称 返回值 说明
getActiveUserRoles() string[] 返回当前用户的角色。另请参阅 Session.getActiveUser()。


    var roles = app.getActiveUserRoles();
    if (roles.indexOf(app.roles.Admins) < 0) {
      throw 'Access denied';
    }
saveRecords(
  records:Record[])		 undefined 从草稿创建新记录（如果记录的 _key 字段为 null）或更新现有记录（ 并非 null）。为新建的记录设置 字段。


    var record = app.models.Person.newRecord();
    app.saveRecords([record]);
deleteRecords(
  records:Record[])		 undefined 删除记录。


    var record = app.models.Person.getRecord(key);
    app.deleteRecords([record]);
getRoleMembers(role:string) string[] 返回属于特定角色的所有成员。


    var role = app.roles.Admins;
    var members = app.getRoleMembers(role);

不会返回您添加到某个角色的群组中的各个成员。

Association

此类表示两个记录之间的关联，一个位于特定关系一端的模型中，另一个位于另一端的模型中（这可能是同一模型。）

每个关联由两个键组成，用于标识关联的记录。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
sourceKey string 关系源端模型中记录的键。使用 Record._sourceKey 访问该记录。
targetKey string 关系目标端模型中记录的键。使用 Record._targetKey 访问该记录。

如要确定关系的哪一端是源，哪一端是目标，请查看关系中模型的 Security 标签页。关系权限具有 Employee + Department 等标题。Employee 和 Department 是关系两端的名称。与第一个关系端对应的模型是源模型，与第二个关系端对应的模型是目标模型。

Model

此类表示应用制作工具中的数据模型。它允许脚本访问此模型的数据记录。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

方法

名称 返回值 说明
deleteRecords(
  keys:string[])		 undefined 按键删除多个记录。
getRecord(
  key:string)		 Record 按键加载一条记录。
getRecords(
  keys:string[])		 Record[] 按键加载几条记录。如果找不到某些键，则返回的记录可以较少。返回记录的顺序与传递键的顺序相同。
newQuery() Query 创建一个查询以加载符合特定条件的当前模型的记录。


    var query = app.models.Person.newQuery();
    query.filters.Name._startsWith = 'John';
    query.filters.Age._greaterThan = 20;
    query.sorting.Name._ascending();
    query.sorting.Age._descending();
    var records = query.run();
newRecord() Record 创建未保存的新记录（草稿记录）。记录得到保存之前，新记录的 _key 字段将为 null。


    var record = app.models.Person.newRecord();
    app.saveRecords([record]);

Query

此类表示应用制作工具中的数据查询。它允许脚本控制数据记录的过滤、排序和分页。当用户启动查询时，应用制作工具会应用所有权过滤条件进行查询，并在将结果返回给用户之前检查结果的权限。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
filters Dynamic 向查询添加过滤条件。支持的过滤条件：equals, notEquals, lessThan, greaterThan, lessThanOrEquals, greaterThanOrEquals, in, notIn, startsWith, notStartsWith, contains, notContains。


    var query = app.models.Person.newQuery();
    query.filters.Name._startsWith = 'John';
    query.filters.Age._greaterThan = 20;
    var records = query.run();

过滤条件 in和 notIn 确认字段中的值是否等于（或不等于）给定数组中的任一值。

过滤条件 startsWith, notStartsWith, contains, notContains 仅支持字符串和字符串列表。

过滤条件 lessThan, greaterThan, lessThanOrEquals, greaterThanOrEquals 仅支持数字、日期和字符串；以及相应的列表数据类型。

查询目录模型时，您只能使用某些过滤条件。如需完整列表，请参阅用户字段和查询运算符。
limit number 设置查询返回的最大记录数。
offset number 设置要跳过而不包含在查询结果中的记录数。
parameters Dynamic 提供对查询脚本中自定义参数的访问权限。
sorting Dynamic 向查询添加排序。


    var query = app.models.Person.newQuery();
    query.sorting.Name._ascending();
    query.sorting.Age._descending();
    var records = query.run();
prefetch Dynamic 向查询添加预取。预取将确保查询的相关记录在同一请求中得到加载，而不是以后访问它们时再按需加载。预取的代价是初始查询耗时增加，但减少了请求总数，因此可以提高总体性能。


    var query = app.models.Employee.newQuery();
    query.prefetch.Manager._add();
    query.prefetch.Manager.Reports._add();

    var records = query.run();
    for (var i in records) {
      var manager = records[i].Manager; // No extra call to DB
      var reports = manager.Reports; // No extra call to DB
      ...
    }

方法

名称 返回值 说明
run() Record[] 执行查询，返回与查询条件匹配的记录。


    var query = app.models.Person.newQuery();
    query.filters.Name._startsWith = 'John';
    query.filters.Name._ascending();
    var persons = query.run();

Record

此类表示应用制作工具中的数据记录。它允许脚本访问记录字段和相关记录。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
_key string 记录键仅在给定模型中具有唯一性。保存记录时生成键，未保存的新记录（草稿记录）的键为 null。
<field> Dynamic 每个记录字段或关系都有一个字段。多对一的关系由简单的字段表示，而多对 N 的关系由数组表示。


    var person = app.models.Person.newRecord();
    person.name = 'John Doe';
    person.age = 35;
    app.saveRecords([person]);

    var manager = app.models.Person.newRecord();
    manager.name = 'Jeff Williams';
    manager.age = 45;
    app.saveRecords([manager]); // You must save new record before using it in relations.

    person.manager = manager;
    app.saveRecords([person]);

Metadata

此类表示应用中的所有元数据。它允许脚本访问此应用的元数据。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
models ModelMetadata[string] 应用中定义的所有模型。

ModelMetadata

此类表示应用制作工具中的元数据模型。它允许脚本访问此模型的元数据。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
description string 模型的说明，在模型编辑器中指定。
displayField Field[string] 模型的显示字段。可以为 null。
fields Field[string] 模型中定义的所有字段。
name string 模型的名称，在模型编辑器中指定。
readOnly bool 模型是否为只读模型。如果模型是只读的，则无法将数据写入此模型。
relations Relation[string] 来自给定模型的所有关系。
type string 模型的数据库类型：Calculated、Cloud SQL 或 Directory。

Field

此类表示应用制作工具中的字段。它允许脚本访问此模型的字段。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
autoIncrement bool 字段是否由数据库自动递增。
defaultValue Dynamic 字段的默认值。可以为 null。
description string 字段的说明。可以为 null。
displayName string 字段的显示名称。可以为 null。
key string 此字段的键。
maxLength number 值的最大长度（以字符为单位）。可以为 null。
maxValue number|date 字段的最大值。可以为 null。
minLength number 值的最小长度（以字符为单位）。可以为 null。
minValue number|date 字段的最小值。可以为 null。
name string 字段的名称。
possibleValues Dynamic[] 显示此字段的所有可能值。可以为 null。
regexp string 所有有效值必须匹配的正则表达式。可以为 null。
regexpError string 正则表达式与用户输入不匹配时向用户显示的错误消息。错误消息中出现的“%s”将替换为用户输入。可以为 null。
required bool 此字段是否为必填项。
type string 字段的类型：String、Number、Date 或 Boolean。
wholeNumber bool 此字段的数字是否是整数。如果数字不包含有效小数位，则该数字是整数。

Relation

此类表示应用制作工具中从指定模型到另一模型的关系的一端。它允许脚本访问此模型的关系。

此类仅存在于应用制作工具应用中。如需了解应用制作工具应用中的所有其他常见类，请参阅应用脚本参考。

属性

名称 类型 说明
ascending bool 端点模型的“排序方式”字段是否按升序排序。
count string 模型的计数（“One”、“Many”）。
model ModelMetadata 关系的端点模型。
name string 关系的端点名称。
owner bool 端点模型是否拥有此关系。

举例来说，如果“Invoice”拥有其“Items”，则 app.metadata.models.Items.relations.Invoice.owner 为 true。
sortBy Field 指定端点模型如何排序的字段。可以为 null。

Transaction

提供对 App Maker 中 Transaction API 的访问。仅在具有至少一个 Cloud SQL 模型的应用中可用。

属性

名称 类型 说明
cloudSql CloudSqlTransaction 控制 Cloud SQL 模型中的事务。
TransactionError function(message:String) 表示发生了事务错误的异常。

CloudSqlTransaction

此类型允许脚本在 Cloud SQL 模型中启动、提交、回滚和检查数据库事务的状态。

属性

名称 类型 说明
isolation IsolationLevel 枚举可能的隔离级别。
lockOnRead LockMode 枚举通过 setLockOnRead() 设置的可能的 Lock On Read 模式。

方法

名称 返回值 说明
isStarted() bool 事务是否正在进行中。


    app.transaction.cloudSql.isStarted();

start
level:IsolationLevel)		 undefined 启动事务。如果另一个事务已在进行中，则会引发错误。


    app.transaction.cloudSql.start(
    app.transaction.cloudSql.isolation.REPEATABLE_READ);

参数是选填项；如果没有传递值，READ_COMMITTED 是默认值。
commit() undefined 提交当前事务。如果应用尝试在事务开始之前提交，则会引发错误。


    app.transaction.cloudSql.commit();

rollback() undefined 还原当前事务中的所有更改并撤消所有数据库锁定。如果应用尝试在事务开始之前回滚，则会引发错误。


    app.transaction.cloudSql.rollback();

setLockOnRead(
lockMode:LockMode)		 undefined 对所有数据库读取应用指定的锁定模式，直到事务完成或使用该方法更改锁定模式。


    app.transaction.cloudSql.setLockOnRead(
    app.transaction.cloudSql.lockOnRead.UPDATE);

IsolationLevel

枚举可能的隔离级别。

属性

名称 类型 说明
READ_UNCOMMITTED IsolationLevel 当前事务可以查看其他事务的未提交更改。了解详情。
READ_COMMITTED IsolationLevel 当前事务可以查看其他事务的已提交更改。了解详情。
REPEATABLE_READ IsolationLevel 当前事务可以查看其他事务的已提交更改。保证记录的所有可重复读取返回相同状态的记录。了解详情。
SERIALIZABLE IsolationLevel 当前事务与其他事务完全隔离。事务依次运行。了解详情。

LockMode

枚举通过 setLockOnRead() 设置的可能的锁定读取模式。

属性

名称 类型 说明
NO_LOCK LockMode 没有应用锁定。默认模式。
SHARE LockMode 其他事务可以读取当前事务锁定的数据，但不能修改它。
UPDATE LockMode 其他事务无法读取或修改当前事务锁定的数据。