README

此仓库包含一个用于 JavaScript 的示例地址簿应用程序，演示如何使用 DreamFactory REST API。它包括新用户注册、用户登录以及相关表的 CRUD 操作。

在本地机器上安装 DreamFactory

要下载和安装 DreamFactory，请选择所需的安装包这里。

配置您的 DreamFactory 实例以运行应用程序

为开发目的启用 CORS。
- 在管理控制台中，导航到配置选项卡，然后单击左侧侧边栏中的 CORS。
- 单击“添加”。
- 将“来源”、“路径”和“头部”设置为 *。
- 将“最大年龄”设置为 0。
- 允许所有 HTTP 动词并勾选“启用”框。
- 完成设置后，单击“更新”。
- 有关设置 CORS 的更多信息，请参阅此处。
为新用户创建默认角色并启用公开注册
- 在管理控制台中，单击“角色”选项卡，然后单击左侧侧边栏中的“创建”。
- 输入角色名称并勾选“活动”框。
- 转到“访问”选项卡。
- 在“服务访问”下添加新条目（稍后可以使其更严格）。
  - 设置服务 = 所有
  - 设置组件 = *
  - 勾选“访问”下所有 HTTP 动词
  - 设置请求者 = API
- 单击“创建角色”。
- 单击“服务”选项卡，然后编辑用户服务。转到“配置”并启用“允许公开注册”。
- 将“公开注册角色 ID”设置为刚刚创建的角色名称。
- 确保“公开注册电子邮件服务 ID”为空，以便新用户可以不进行电子邮件确认而注册。
- 保存更改。
导入应用程序的包文件。
- 从管理控制台中的“应用程序”选项卡，单击“导入”，然后在示例应用程序列表中单击“JavaScript 地址簿”。地址簿包包含应用程序描述、源代码、模式和示例数据。
- 留空存储服务和文件夹。它将使用名为“files”的默认本地文件服务。
- 单击“导入”按钮。如果成功，您的应用程序将显示在“应用程序”选项卡上。您可能需要刷新页面才能在列表中看到您的新应用程序。
决定您是要在本地运行应用程序还是从实例加载它。
- 对于本地运行，将仓库克隆到您的机器上，并在浏览器中打开 index.html。如果本地运行，您需要设置实例的 URL，以便应用程序可以进行 API 调用。转到您的本地仓库并编辑 script.js。将常量 INSTANCE_URL 设置为指向您的 DreamFactory 实例，例如 http://localhost:8080。
- 要从实例运行，请直接从管理控制台的“应用程序”选项卡中启动应用程序。将 INSTANCE_URL 设置为空字符串。
如果从实例运行，请使应用程序文件公开。
- 确定应用程序文件存储的位置。如果您使用默认存储设置导入应用程序，它将是名为“files”的默认本地文件服务。
- 在管理控制台中的“文件”选项卡下。找到您的文件服务。双击并找到您的应用文件夹，例如：AddressBookForJavaScript。
- 在管理控制台的“服务”选项卡中点击“files”服务。点击“配置”选项卡，并将文件夹名AddressBookForJavaScript作为公开路径添加。现在从容器下拉列表中选择相关容器。如果您使用默认存储设置导入应用，则从下拉列表中选择local。保存您的更改。
编辑您的应用API密钥
- 如果您从实例运行，请使用文件管理器编辑script.js并将APP_API_KEY设置为新的应用密钥。API密钥显示在管理控制台“应用”选项卡中的应用详情中。
- 如果您本地运行，请编辑本地仓库中的script.js。
确保您有一个名为db的SQL数据库服务。大多数DreamFactory实例都有一个默认的db服务用于SQLite。您可以通过在管理控制台的“服务”选项卡中创建新的SQL服务来添加一个。确保您将名称设置为db。

运行通讯录应用

您可以从管理控制台的“应用”选项卡启动应用，或通过在浏览器中打开本地index.html。

当应用启动时，您可以注册新用户或以现有用户登录。目前，该应用不支持注册和登录管理员用户。

示例API调用

DreamFactory JavaScript通讯录使用AJAX进行API调用，而文件functions.js包含CRUD操作的常用函数。

DreamFactory REST API调用的通用形式是

<rest-verb> http[s]://<server-name>/api/v2/[<service-api-name>]/[<resource-path>][?<param-name>=<param-value>]

JavaScript应用AJAX调用格式是

     dataType: String
  contentType: String
          url: String
         data: String,Object
       method: String
      headers: Object

分解每个参数

dataType 返回数据的格式。这取决于应用程序，但通常为JSON。
contentType 发送到API的数据格式。这通常是JSON和字符集UTF-8。
url 包含通用调用中的http[s]://<server-name>/api/v2/[<service-api-name>]/[<resource-path>]的值。您可以将查询参数包含在这里。但是，通过使用data参数传递查询参数比将其格式化到url中更容易和更干净。
data （可选）查询参数。
method REST动词。
headers 标头对象必须包括应用程序特定的API密钥和会话令牌。

登录和注册示例

// if the app is imported to the DreamFactory instance leave INSTANCE_URL blank. Email and password are typically input fields in the app UI.
var INSTANCE_URL = 'http[s]://<server-name>';
var email         = 'my@email.com';
var password      = 'mypassword';

$.ajax({
   dataType: 'json',
   contentType: 'application/json; charset=utf-8',
   url: INSTANCE_URL + '/api/v2/user/session',
   data: JSON.stringify({
      'email': email,
      'password': password
   }),
   method:'POST',
   success:function (response) {
      // Handle success
   },
   error:function (response) {
      // Handle error
   }
});

user/session API请求将返回会话令牌。

注册

// Email and password are typically input fields in the app UI.
var firstname    = 'firstname';
var lastname     = 'lastname';
var email        = 'email';
var new_password = 'new_password';

$.ajax({
   dataType: 'json',
   contentType: 'application/json; charset=utf-8',
   url: INSTANCE_URL + '/api/v2/user/register?login=true',
   data: JSON.stringify({
      'first_name': firstname,
      'last_name': lastname,
      'email': email,
      'new_password': password
   }),
   method:'POST',
   success:function (response) {
      // Handle success
   },
   error:function (response) {
      // Handle error
   }
});

当在url中附加（可选的）login=true参数时，API请求将返回会话令牌。因此，附加此参数后，新注册的用户不需要登录即可获取会话令牌。

登录和注册示例说明了如何向DreamFactory发出API请求。此通讯录应用具有常见的API请求类型的函数，因此在以下示例中使用这些函数。

获取记录示例

获取表中的所有记录

// Use the function `getRecords()` function to get all records from the **contact_group** table.
// Usage: getRecords(table, params, token, callback)   -   params can be fields, filters etc.

$.api.getRecords('contact_group', null, session_token, callback);

// create a callback function and handle the returned data there
var callback = function(response) {
    // The response contains an array of group objects
}

获取特定字段

// only need to get the contact_id and full contact name
// set the fields param to give us just the fields we need
var params = 'fields=contact_id,first_name,last_name';
$.api.getRecords('contacts', params, session_token, callback);

应用过滤条件获取

// create filter to get only the contact ids in the group id 10
// note the equal sign is url encoded (%3D) in the filter value;
var params = 'filter=contact_group_id%3D10';
$.api.getRecords('contact_group_relationship', params, session_token, callback);

创建记录

// Store a group by posting a stringified object. The API request will return the new group id if successful.
var group  = { resource: [ { name: 'My Group' } ] };
var params = JSON.stringify(group);
$.api.setRecord('contact_group', params, session_token, callback);

删除记录

根据ID删除单个记录

// a single record can be deleted by id.
$.api.deleteRecord('contact', null, session_token, callback);

根据ID删除多个记录

// one or more records from e.g. contact can be deleted by adding one or more ids to the parameter.
var params = ids=1,2,3;
$.api.deleteRecord('contact', params, session_token, callback);

根据字段条件条件删除记录

// delete all records matching field conditions, in this case all contacts with the last name 'Smith'.
var params = 'filter=last_name%3DSmith';
$.api.deleteRecord('contact', params, session_token, callback);

其他资源

有关DreamFactory REST API的更详细信息，请参阅此处。

管理控制台中包含的实时API文档是学习DreamFactory REST API如何工作的好方法。

dreamfactory / javascript-sdk

维护者

详情