为 Fa31/ade REST Service 实施定制 API

开发移动应用程序时，通常首先从用户界面层开始，然后使用 REST Web 服务将应用程序与其他应用程序连接起来。此方法适用于小型应用程序或简单应用程序。如果应用程序更大，并且您希望与多个后端服务连接，则可能会无意中引入性能和安全问题。

最佳做法是开始在外部后端服务和用户界面之间构建淡出 API 层，以尽可能减少对后端服务的调用数。例如，移动应用程序可以对流式 API 层执行单次调用，该层处理对其他 REST 服务的调用，并将所有传入数据合并为移动应用的单个响应。

创建完整的自定义 API

使用 Oracle Mobile Hub 创建完整的定制 API。

单击，然后从侧面的菜单中依次选择开发和 api。如果 API 已创建（无论是处于草稿还是已发布状态），您将看到 API 列表。如果没有定制 API，则您将看到包含新 API 按钮的页。单击您已创建的 API，或单击新建 API 以开始。

定义端点

可以创建资源来定义 API 的端点。资源是一个 API 的面包屑。它具有一种类型，一些数据与之关联，是与其他资源的关系，并且包含一种或多种操作方法。资源可以接近任何内容：图像、文本文件、其他资源的集合、逻辑事务处理、过程等。

单击端点导航链接以开始。
单击新建资源，然后添加一些基本信息。

每次单击新建资源时，都会创建顶级（根）资源。如果要添加子资源（嵌套），请单击顶级资源旁边的添加 (+)。单击 X 可删除资源。

注 :
要查看“方法 ”链接下的图标？每次为资源定义方法时，该资源的图标都会显示在“方法”链接下。将这些方法用作快捷方式可以查看已为资源定义了哪些方法。单击图标可直接转到“方法”页上的定义。
提供资源路径，即 URI （相对于基本 URI）。例如，如果基础 URI 为/mobile/custom/audits/，则可以添加资源 findings，即/mobile/custom/audits/findings。
提供显示名称，该名称是帮助在 API 文档中识别的资源的名称。
资源按其在“API 测试”页左侧的显示名称列出。
提供资源的简要说明。

输入说明后，URI 将显示在说明字段下方。
（可选）提供 RAML 资源类型，该资源类型是资源类型(resourcesType:)。您无需指定资源类型。如果要使用资源类型但未定义任何资源类型，则单击类型链接并定义一个。

为资源创建方法时，“方法”链接下方将显示该方法的符号。如果需要检查资源定义，可以立即看到为资源定义了哪些方法。单击图标可直接转到该方法定义。

您可以通过切换到简略模式（即新资源右侧）来清除混乱以更快地查找资源。简略显示可隐藏资源说明、资源类型和路径。

将方法添加到资源

方法是可以在资源上执行的操作。“方法”页显示一次一个方法。在至少定义两个方法之后，可以单击该页顶部的某个方法的图标以查看其详细资料。

通过单击方法将某些方法添加到资源。

如果您要为其定义方法的资源具有路径参数，则这些参数显示在添加方法上方。
1. （可选）如果希望用每种方法传递路径参数，请单击必需。
  将显示参数名称。
2. 提供参数的显示名称和示例代码。
3. 从下拉列表中，为参数选择有效的值类型。
单击添加方法，然后选择所需的方法。

选择方法后，方法列表中将不再列出该方法，因为每个资源只使用一次方法（例如，无法为单个资源定义两个 DELETE 方法）。此时将在页顶部显示您定义的每个方法的图标。单击方法图标可直接转到其定义。
（可选）在说明字段中输入方法的简要说明。
（可选）输入方法的显示名称。
（可选）提供要应用于此方法的任何培训。

如果未定义任何资源特性，请单击端点以返回到主“资源”页，然后单击特性链接以定义一个资源。使用 Trait 可以定义类似操作的集合。

定义资源的方法后，可以为这些方法定义请求和响应。

定义方法的请求

现在您已选择了方法，请定义您要连接到的服务的请求。例如，如果选择了 POST 方法，则现在可以定义要创建的内容。为此，请添加参数和请求主体，其中包含要发送到服务的数据的说明。

单击请求可定义请求。
单击添加参数，然后选择参数类型：查询或标头。如果方法需要参数，请选择必需。
1. 为参数指定名称和显示名称。
2. 选择有效的值类型：字符串、数字、整数、日期或布尔。
3. （可选）提供参数的说明和可在测试端点的有效性时使用的示例。例如，可以具有资源 audits，并添加查询参数 auditorID，该参数采用数字值，而另一个采用字符串值的参数 auditName：
```
/audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"
```
  在此示例中，使用查询参数 auditorID 和 auditName 定义 GET 方法。
4. （可选）单击更多属性可向参数添加嵌套属性。单击重复可添加当前参数的倍数。
5. 单击添加参数可为方法添加其他顶级参数。
根据所选择的方法，单击添加介质类型并定义方法主体。正文包含您要发送到服务器的数据。例如，如果您要定义 POST 方法，则需要定义您要创建的项，例如新的客户列表或服务请求。如果要定义 GET 方法，则不需要发送方法主体，因此无需指定介质类型。
1. 为方法主体选择介质类型，这是所发送消息的格式，例如文本、图像或 Web 表单。
  根据类型（例如，您不会输入图像类型的方案），可以选择添加方案和/或示例。
  定义方案时，仅添加资源用途所需的数据。也就是说，不要添加只会降低传输速度的不必要数据，并且可能会增加错误的可能性。
2. （可选）单击方案，然后在编辑器窗格中输入一个方案（采用 JSON 格式）。方案与主体的模板类似。用来定义消息内容的功能。
3. （可选）单击示例，然后在编辑器窗格中输入示例（以 JSON 格式），模拟实施将其用作方法的模拟响应。使用模拟数据可以帮助您验证方法的行为。此示例显示要在消息正文中发送的数据的模拟值，如 audits 资源的 POST 方法中所定义：
```
body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }                               
```
单击添加介质类型可添加其他介质类型。如果决定不需要该方法，请单击标帜中的 X 将其删除。

定义方法的响应

根据请求，您可能需要响应，也可能不需要响应。响应描述了从服务返回结果的流程。您可能希望定义一个响应，该响应验证您请求的数据是否返回，或者您可能希望响应确认是否已收到请求。定义响应类似于定义请求。主要区别在于，您需要选择状态代码以通知您连接的结果。

单击响应以定义一个或多个响应。
单击添加响应，然后选择要返回的状态代码。
默认情况下会提供状态代码 200，但如果它不是所需的代码，则从下拉列表中选择一个状态代码。
- 2 xx 表示成功连接。
- 3 xx 表示发生重定向。
- 4 xx 表示出现用户错误。
- 5 xx 表示出现服务器错误。
为了帮助任何人使用 API 来了解您配置的 API 中可能出现的错误的原因，请使用 HTTP 状态代码返回最能与错误情形匹配的代码。
提供代码指定内容的说明。
单击添加标头，选择响应标头或查询，提供标头或查询的名称以及标头的显示名称，以及标题的有效值类型。
单击添加介质类型，然后选择响应的格式。根据所选介质类型，您可以添加参数、方案或示例，就像为请求主体添加一样。
1. 对于基于文本的介质类型（例如，application/json 或 text/xml），单击方案为正文输入方案（JSON 格式）。
  与请求正文一样，只将相关数据添加到响应正文中。请勿包含比操作实际需要更多的数据。
2. 单击示例以为响应正文添加模拟数据（采用 JSON 格式）。在使用真实数据进行测试之前，可以使用模拟数据来验证方法的行为。
3. 对于基于表单的介质类型（例如 multipart/form-data），如果参数是必需的，请单击添加参数并选中必需。然后，提供名称并选择值类型。（可选）可以为参数指定名称。
4. 对于基于图像的介质类型（例如 image/png），无需执行任何操作，因为没有可提供的方案或属性。

以下示例显示已创建 audits 资源的 POST 方法的响应 , 状态代码为 201, 指示已成功创建新资源。该示例还显示 application/json 的返回响应格式、已添加的 Location 标头以及包含模拟数据的消息正文：

responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

定义响应时，可以决定测试端点，或者单击导航栏中的端点以返回主资源页。您可以从此处转到 API 设计器中的其他页，以创建根、资源类型或特点，或者添加 API 文档。

如果决定不需要该方法，请单击标帜中的 X 将其删除。

创建 REST 连接器 API

使用“REST 连接器 API”向导可以创建、配置和测试连接器 API。

要获取基本的工作连接器 API，您可以提供一个小名称作为连接器 API 以及指向外部服务的 URL。

在此页中，您可以执行以下操作：

定义规则以构成要访问的数据的特定请求或响应。
为您正在访问的服务配置客户端安全策略。
测试连接并测试对连接执行的调用的结果。

必须创建定制 API 和实施以使应用程序能够调用连接器 API，以及自动生成 API 和实施。如果您希望手动执行此操作，则必须使用适当的资源创建定制 API，然后实施定制代码。

设置基本连接器

通过完成"REST Connector API"向导中的前两页，可以创建功能连接器。

单击，然后从侧面的菜单中依次选择开发和 api。
单击 REST（如果这是要创建的第一个连接器 API）或新建连接器，然后从下拉列表中选择 REST。
通过提供以下信息标识新的 REST 连接器 API：
1. API 显示名称：连接器 API 列表中显示的名称。
2. API 名称：连接器 API 的唯一名称。
  
  默认情况下，此名称附加到相对基础 URI 作为连接器 API 的资源名称。您可以在 API 名称字段下方看到基础 URI。
  
  除此连接器 API 的新版本以外，其他连接器 API 不能具有相同的资源名称。
3. 简要说明：选中此 API 时，将在“连接器”页上显示此说明。
单击创建。
在 REST 连接器 API 对话框的“一般信息”页中，设置超时值：
- HTTP 读取超时：等待读取数据所用的最长时间（毫秒）。如果未提供值，则将应用默认值 20 秒。
- HTTP 连接超时：连接到远程 URL 所用的时间（毫秒）。0mms 值表示允许不限制超时。
  
  HTTP 超时值必须小于 Network_HttpRequestTimeout 策略 , 该策略的默认值为 40,000 毫秒。
  
  注 :
  如果除了服务开发人员角色之外，您还有一个移动云管理员角色，则可以从管理员视图打开 policies.properties 文件，查看当前环境的网络策略值。否则，请要求移动云管理员获取值。
单击描述符，然后输入服务的连接信息。

如果提供 Swagger 描述符 URL，则将标识并显示可用资源，您可以选择需要的资源。

注 :
仅支持标准 Internet 访问端口 80 和 443。无法使用定制端口建立与服务的连接。
单击保存。
（可选）单击测试，选择验证身份证明，然后对服务进行测试调用。

从这里可以通过以下方式进一步配置连接器：

（如果已在“描述符”页上提供描述符）转到“资源 ”页，然后选择已公开资源的方法。
定义规则。
设置安全策略。

为确保连接器 API 配置有效，应在发布之前对其进行全面测试（不只是来自“连接器 API 测试”页）。也就是说，您还应测试使用此连接器 API 的定制 API （及其实施）。基本而言，如果您已准备好发布连接器 API，则还应该准备好发布调用它的定制 API。

设置规则

可以设置规则以定义移动应用程序与服务之间的交互。规则提供了一种方法，可用于为服务上的所有资源调用、调用特定代理路径和特定类型操作（动词）的调用添加默认参数值。这有助于强制使用 URL 字符串的一致语法，保存自定义代码开发人员不必插入这些值，从而可以通过分析来跟踪不同调用。

您可以创建一个或多个规则。每个规则可以具有一个或多个 Query 和 Header 类型的参数。

如果未应用任何规则，则所有调用都将通过代理传递到现有服务。

如果连接器尚未打开，请单击，然后从侧菜单中依次选择开发和 api。
选择要编辑的连接器 API，然后单击打开。
选择角色。
单击新建规则。
单击添加参数，选择查询或标头参数类型，然后输入查询名或标头名称及其值。

注 :

虽然您可以定义规则以默认设置特定标头，但如果客户端通过自定义代码直接或间接（例如从 Web 浏览器或移动应用程序）调用连接器，则不会应用这些规则。

特别是，设置请求正文的格式通常是使用 Content-Type 标头（而不是 REST Connector 规则）在定制代码中完成的。同样，设置响应正文的格式也是使用 Accept 标头（而不是 REST Connector 规则）在定制代码中执行的。

您可以根据需要向规则中添加尽可能多的参数，但更好不要使具有太多操作的规则超载。更简单的规则结构可以更轻松地进行故障排除。
展开资源，然后编辑远程 URL 以为要应用到的规则提供资源。基本 URL 值是您在设置基本信息步骤中输入的值，无法编辑。
如果希望将规则仅应用于在远程 URL 中指定的资源级别，请选择不应用到较低级别的资源。
（可选）取消选择不希望应用于刚定义的规则的 HTTP 方法。默认情况下，所有方法都处于选中状态。
（可选）单击新建规则以创建另一个规则。

注 :

如果定义的规则与其他规则冲突，则首先应用的规则优先，并忽略冲突的规则。

完成后，单击保存，然后单击下一步 (>)转到配置连接器 API 的下一步。

您刚刚定义的规则的说明显示在“默认参数 ”部分上方的规则标帜中。例如，假设提供了以下值：

远程 URL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
本地 URI = myMapAPI
具有以下参数的规则：Query:key:A3FAEAJ903022
GET 和 PUT HTTP 方法

规则说明如下：

对于在myMapAPI /方向上提供的httpsInstall /maps.googleapis.com/maps/api/directions/jsonwlsoriginus.oracle.comlos+angeles&destinationPtrLoc seattle ，包括查询： key = A3FAEAJ903022。

如果未创建规则，说明将为：

对于在myMapAPI中提供的所有Metric HODS到 https31//maps.googleapis.com/maps/api/instructions ，将不会应用默认参数。

现在，您有一个映射到现有服务的基础 URI。使用示例：

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle 映射到https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

配置安全策略和覆盖属性

在结束连接器 API 之前，您应考虑如何处理其安全性。可以使用安全策略或授权标头。选择安全策略，该策略描述要连接到的服务的验证方案是建议的方法。

每个安全策略都具有可以配置的名为覆盖的属性。覆盖策略配置属性的一个原因是限制必须维护的策略数：而不是使用略有多种不同的配置创建多个策略，可以使用相同的一般策略和覆盖特定值来满足您的要求。

要选择安全策略并设置策略覆盖，请执行以下操作：

如果连接器尚未打开，请单击，然后从侧边菜单中依次选择开发和 api。
选择要编辑的连接器 API，然后单击打开。
选择安全性。
从可用策略列表中选择安全策略，然后单击右箭头将其移到所选策略列表中。
请为连接器 API 仅选择一个策略。所选策略的说明将显示在列表下方。
如果不希望使用默认值，请指定覆盖（如果适用）以选定策略。
要覆盖属性，请输入或选择默认值之外的值。
单击保存以保存您的工作，或单击保存并关闭以保存您的工作并退出 REST Connector API 向导。
单击下一步 (>)可转到下一步。