为传真 REST 服务实施定制 API

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

最好的做法是开始在外部后端服务与用户界面之间构建 fachunade API 层，以减少每当可能时对后端服务的调用次数。例如，您的移动应用程序可以对 fachunade 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/，则可以添加 /mobile/custom/audits/findings 资源 findings。
4. 提供显示名称，这是资源的名称，可以方便地在 API 文档中识别。
   资源按其在“API 测试”页左侧的显示名称列出。
5. 提供资源的简要说明。

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

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

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

通过切换到压缩模式（该模式位于新资源的右侧），您可以清除混乱以更快地定位资源。简略显示将隐藏资源说明、资源类型和路径。

将方法添加到资源

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

1. 单击方法将某些方法添加到资源中。

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

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

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

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

   如果未定义任何资源属性，请单击端点以返回主资源页，然后单击训练链接以定义一个。通过培训可以定义类似操作的集合。

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

定义方法的请求

现在您已选择方法，定义要连接到的服务的请求。例如，如果选择了 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. 单击添加介质类型可添加其他介质类型。如果您决定不希望使用该方法，请单击标帜中的 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 Connector 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 的唯一名称。

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

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

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

4. 单击创建。

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

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

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

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

     注 :

     如果在您的服务开发人员角色之外具有移动云管理员角色，您可以打开 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 Connector 规则）设置请求正文的格式。同样，设置响应正文的格式也是在带有 Accept 标头的定制代码中完成的，而不是作为 REST Connector 规则。

   可以根据需要向规则添加任意多个参数，但最好不要使具有过多操作的规则超载。更简单的规则构造更易于进行故障排除。

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 上可用的所有 METHODS 到 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 Connector API 向导。
7. 单击下一步 (>)可转到下一步。