为外观 REST 服务实施定制 API

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

最好在外部后端服务和用户界面之间开始构建外观 API 层，以尽可能减少对后端服务的调用次数。例如，您的移动应用可以对外墙 API 层执行一次调用，该层处理对其他 REST 服务的调用，并将所有传入数据合并到对移动应用的单个响应中。

创建完整的定制 API

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

单击 ，然后从侧边菜单中选择开发，然后选择 API 。如果 API 已创建（无论是处于草稿还是已发布状态），您将看到 API 列表。如果不存在定制 API，您将看到包含新建 API 按钮的页。单击已创建的 API，或者单击新建 API 以开始。

定义端点

您可以创建资源来定义 API 的端点。资源是 API 的核心。它有一个类型，一些与之关联的数据，与其他资源的关系，并包含一个或多个对它起作用的方法。资源几乎可以是任何东西：图像、文本文件、其他资源的集合、逻辑事务处理、过程等。

1. 单击端点导航链接以开始。
2. 单击新建资源并添加一些基本信息。

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

   注意：

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

   输入说明后，URI 将显示在说明字段下方。

6. （可选）提供 RAML 资源类型，即资源类型 (resourcesType:)。不需要指定资源类型。如果要使用资源类型但未定义资源类型，请单击类型链接并定义一个。

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

通过切换到紧凑模式（位于新资源的右侧），可以清除杂乱以更快地找到资源。紧凑显示隐藏资源说明、资源类型和路径。

将方法添加到资源

方法是对资源执行的操作。“Methods（方法）”页一次显示一个方法。定义至少两个方法后，可以单击页面顶部的某个方法的图标以查看其详细信息。

1. 通过单击方法将一些方法添加到资源。

   如果要为其定义方法的资源具有路径参数，则它们将显示在添加方法上方。

   1. （可选）如果希望通过每种方法传递路径参数，请单击必需。
      此时将显示参数名。
   2. 为参数和示例代码提供显示名称。
   3. 从下拉列表中选择参数的有效值类型。
2. 单击添加方法，然后选择所需的方法。

   选择某个方法后，该方法将不再列在方法列表中，因为每个资源仅使用一次方法（例如，无法为单个资源定义两个 DELETE 方法）。您定义的每个方法的图标显示在页面顶部。单击方法图标可直接转到其定义。

3. （可选）在“说明”字段中输入方法的简要说明。
4. （可选）输入方法的显示名称。
5. （可选）提供要应用于方法的任何特性。

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

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

定义方法的请求

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

1. 单击请求以定义请求。
2. 单击添加参数并选择参数类型：查询或标题。如果该方法需要该参数，请选择必需。
   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. 单击添加参数可为方法添加其他顶层参数。
3. 根据所选方法，单击添加介质类型并定义方法主体。正文包含要发送到服务器的数据。例如，如果要定义 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"
            }                               
      

4. 单击 Add Media Type（添加介质类型）以添加其他介质类型。如果您决定不需要该方法，请单击标题中的 X 以将其删除。

定义方法的响应

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

1. 单击响应可定义一个或多个响应。
2. 单击添加响应，然后选择要返回的状态代码。

   默认情况下会提供状态代码 200，但如果这不是所需的代码，则从下拉列表中选择一个状态代码。

   • 2 xx 表示连接成功。

   • 3 xx 指示发生了重定向。

   • 4 xx 指示发生了用户错误。

   • 5 xx 指示发生了服务器错误。

   要帮助使用 API 的用户了解所配置的 API 中可能出错的原因，请使用 HTTP 状态代码返回与错误情况最匹配的代码。

3. 提供代码指定的内容的说明。
4. 单击添加标头，选择响应标头或查询，提供标头或查询的名称和标头的显示名称，以及标头的有效值类型。
5. 单击添加介质类型，然后选择响应的格式。根据您选择的介质类型，您可以添加参数、方案或示例，就像您为请求主体所做的那样。
   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 向导中的前两页来创建正常运行的连接器。

1. 单击 ，然后从侧边菜单中选择开发，然后选择 API 。

2. 单击 REST （如果这是要创建的第一个连接器 API）或新建连接器，然后从下拉列表中选择 REST 。

3. 通过提供以下项来确定新的 REST 连接器 API：

   1. API 显示名称：连接器 API 列表中将显示的名称。

   2. API 名称：连接器 API 的唯一名称。

      默认情况下，此名称附加到相对基 URI 作为连接器 API 的资源名称。您可以在 API 名称字段下方看到基本 URI。

      除了此连接器 API 的新版本之外，其他连接器 API 不能具有相同的资源名称。

   3. 简短说明：选择此 API 时，此说明将显示在“连接器”页上。

4. 单击创建。

5. 在“REST 连接器 API”对话框的“一般信息”页中，设置超时值：

   • HTTP 读取超时：等待读取数据所需的最长时间（毫秒）。如果未提供值，则应用默认值 20 秒。

   • HTTP 连接超时：连接到远程 URL 所花费的时间（毫秒）。值为 0mms 表示允许无限超时。

     HTTP 超时值必须小于默认值为 40,000 毫秒的 Network_HttpRequestTimeout 策略。

     注意：

     如果您除了服务开发人员角色外还具有移动云管理员角色，则可以从“管理员”视图打开 policies.properties 文件以查看当前环境的网络策略值。否则，请向移动云管理员询问值。

6. 单击描述符，然后输入服务的连接信息。

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

   注意：

   仅支持标准 Internet 访问端口 80 和 443。无法使用定制端口连接到服务。

7. 单击保存。

8. （可选）单击测试，选择验证身份证明，然后对服务进行测试调用。

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

• （如果已在“描述符”页上提供了描述符）转到资源页，然后选择公开资源的方法。

• 定义规则。

• 设置安全性策略。

为了确保您的连接器 API 配置有效，您应在发布之前对其进行彻底测试（而不仅仅是来自“连接器 API 测试”页）。也就是说，您还应该测试使用此连接器 API 的定制 API（及其实现）。从本质上讲，如果您准备发布连接器 API，您也应该准备好发布调用它的定制 API。

设置规则

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

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

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

1. 如果连接器尚未打开，请单击 ，然后从侧边菜单中选择开发，然后选择 API 。
2. 选择要编辑的连接器 API，然后单击打开。
3. 选择角色。
4. 单击新建规则。
5. 单击添加参数，然后选择查询或页眉参数类型，并输入查询或页眉名称及其值。

   注意：

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

   特别是，设置请求正文的格式通常在带有 Content-Type 标头的定制代码中完成，而不是作为 REST 连接器规则。同样，设置响应正文的格式也是在带有 Accept 标头的定制代码中完成的，而不是作为 REST 连接器规则。

   您可以根据需要向规则添加任意数量的参数，但最好不要重载操作过多的规则。更简单的规则构造更容易进行故障排除。

6. 展开资源，然后编辑远程 URL，为要应用的规则提供资源。基本 URL 值是在设置基本信息步骤中输入的值，无法编辑该值。
7. 如果希望规则仅应用于远程 URL 中指定的资源级别，请选择不应用于较低级别资源。
8. （可选）取消选择不希望应用于刚定义的规则的 HTTP 方法。默认情况下，所有方法都处于选中状态。
9. （可选）单击新建规则以创建另一个规则。

   注意：

   如果定义的规则与其他规则冲突，则应用的第一个规则优先，并且冲突规则将被忽略。

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

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

• 远程 URL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

• 本地 URI = myMapAPI

• 具有以下参数的规则：Query:key:A3FAEAJ903022

• GET 和 PUT HTTP 方法

规则说明如下所示：

对于可从 myMapAPI/directions 获取的 GET 到 https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle，请包括 Query:key=A3FAEAJ903022。

如果未创建规则，则说明如下：

对于 myMapAPI 上提供的 https://maps.googleapis.com/maps/api/directions 的所有方法，将不应用任何默认参数。

现在，您有一个映射到现有服务的基本 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 之前，应考虑如何处理其安全性。您可以使用安全策略或授权标头。建议使用一种安全策略来描述要连接到的服务的验证方案。

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

要选择安全策略并设置策略覆盖：

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