为函数创建 OpenAPI 定义

通常使用 OpenAPI 定义(以前称为 Swagger 文件)描述 REST API。 此定义中包含的信息涉及 API 中哪些操作可用,以及 API 的请求和响应数据应采用怎样的结构。

本教程将创建确定风力涡轮机上的紧急修复是否经济高效的函数。 然后为该函数应用创建一个 OpenAPI 定义,使该函数可使用其他应用和服务进行调用。

本教程介绍如何执行下列操作:

  • 在 Azure 中创建一个函数
  • 使用 OpenAPI 工具生成 OpenAPI 定义
  • 修改定义以提供额外的元数据
  • 通过调用函数测试定义

创建函数应用

必须使用函数应用托管函数的执行。 函数应用可将函数分组为逻辑单元,以便更轻松地管理、部署、缩放和共享资源。

  1. 选择 Azure 门户左上角的“新建”按钮,然后选择“计算” > “Function App”。

    在 Azure 门户中创建函数应用

  2. 使用图像下面的表格中指定的函数应用设置。

    定义新的函数应用设置

    设置 建议的值 说明
    应用名称 全局唯一名称 用于标识新 Function App 的名称。 有效的字符是 a-z0-9-
    订阅 你的订阅 要在其下创建此新函数应用的订阅。
    资源组 MyResourceGroup 要在其中创建 Function App 的新资源组的名称。
    存储 全局唯一名称 Function App 使用的新存储帐户的名称。 存储帐户名称必须为 3 到 24 个字符,并且只能包含数字和小写字母。 也可以使用现有帐户。
    应用服务计划/位置 应用服务计划是应用的容器。 应用服务计划的设置确定与应用关联的位置、功能、成本和计算资源。
  3. 选择“创建”以预配和部署函数应用。

  4. 选择门户右上角的“通知”图标,留意是否显示“部署成功”消息。

    定义新的函数应用设置

  5. 选择“转到资源”,查看新的函数应用。

Tip

如果在门户中找不到函数应用,请尝试将 Function App 添加到 Azure 门户中的收藏夹

创建函数

本教程使用的 HTTP 触发函数采用两个参数:修复涡轮机的估计时间(小时)、涡轮机的容量(千瓦特)。 然后函数计算修复的费用和涡轮机 24 小时可以产生的收入。

  1. 展开 Function App,选择“Functions”旁边的 + 按钮。 如果这是 Function App 中的第一个函数,请选择“自定义函数”。 此时将显示函数模板的完整集合。

    Azure 门户中的 Functions 快速入门页

  2. 在搜索字段中,键入 http,然后针对 HTTP 触发器模板选择“C#”。

    选择 HTTP 触发器

  3. 为函数键入 TurbineRepair 作为名称,选择 Function 作为身份验证级别,然后选择“创建”。

    创建 HTTP 触发的函数

  4. 将 run.csx 文件的内容替换为以下代码,然后单击“保存”:

    using System.Net;
    
    const double revenuePerkW = 0.12; 
    const double technicianCost = 250; 
    const double turbineCost = 100;
    
    public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
    {   
    
        //Get request body
        dynamic data = await req.Content.ReadAsAsync<object>();
        int hours = data.hours;
        int capacity = data.capacity;
    
        //Formulas to calculate revenue and cost
        double revenueOpportunity = capacity * revenuePerkW * 24;  
        double costToFix = (hours * technicianCost) +  turbineCost;
        string repairTurbine;
    
        if (revenueOpportunity > costToFix){
            repairTurbine = "Yes";
        }
        else {
            repairTurbine = "No";
        }
    
        return req.CreateResponse(HttpStatusCode.OK, new{
            message = repairTurbine,
            revenueOpportunity = "$"+ revenueOpportunity,
            costToFix = "$"+ costToFix         
        }); 
    }
    

    此函数代码返回 YesNo 的消息,指示紧急修复是否经济高效以及涡轮机产生的收入机会和修复涡轮机的费用。

  5. 若要测试该函数,请单击最右边的“测试”展开“测试”选项卡。在“请求正文”中输入以下值,然后单击“运行”。

    {
    "hours": "6",
    "capacity": "2500"
    }
    

    在 Azure 门户中测试函数

    响应正文中将返回以下值。

    {"message":"Yes","revenueOpportunity":"$7200","costToFix":"$1600"}
    

现在已经有了确定紧急修复是否经济高效的函数。 接下来,请为该函数应用生成并修改 OpenAPI 定义。

生成 OpenAPI 定义

现在即可生成 OpenAPI 定义。 其他 Microsoft 技术(例如 API 应用,以及 Postman 等第三方开发者工具和其他许多包)也可以使用此定义。

  1. 请仅选择 API 支持的“谓词”(本示例中为 POST)。 这样可以生成更干净的 API 定义。

    1. 在新 HTTP 触发器函数的“集成”选项卡上,将“允许的 HTTP 方法”更改为“选定的方法”。

    2. 在“选定的 HTTP 方法”中,清除除“POST”外的所有选项,然后单击“保存”。

      选定的 HTTP 方法

  2. 单击函数应用名称(如“function-demo-energy”)>“平台功能” > API 定义”。

    API 定义

  3. 在“API 定义”选项卡上,单击“函数”。

    API 定义源

    此步骤为 Function App 启用一套 OpenAPI 选项,其中包括一个用于托管 Function App 域中的 OpenAPI 文件的终结点、一个 OpenAPI 编辑器的内联副本和一个 API 定义模板生成器。

  4. 单击“生成 API 定义模板” > “保存”。

    生成 API 定义模板

    Azure 会在 Function App 中扫描 HTTP 触发器函数,并使用 functions.json 中的信息生成 OpenAPI 定义。 下面是生成的定义:

    swagger: '2.0'
    info:
    title: function-demo-energy.chinacloudsites.cn
    version: 1.0.0
    host: function-demo-energy.chinacloudsites.cn
    basePath: /
    schemes:
    - https
    - http
    paths:
    /api/TurbineRepair:
        post:
        operationId: /api/TurbineRepair/post
        produces: []
        consumes: []
        parameters: []
        description: >-
            Replace with Operation Object
            #http://swagger.io/specification/#operationObject
        responses:
            '200':
            description: Success operation
        security:
            - apikeyQuery: []
    definitions: {}
    securityDefinitions:
    apikeyQuery:
        type: apiKey
        name: code
        in: query
    

    此定义描述为“模板”,因为它需要更多元数据才能组成完整的 OpenAPI 定义。 下一步会修改定义。

修改 OpenAPI 定义

生成模板定义后,接下来可以修改模板,以提供其他关于 API 操作和数据结构的元数据。 在“API 定义”中,删除从 post 到定义的底部生成的定义,粘贴以下内容,然后单击“保存”。

    post:
      operationId: CalculateCosts
      description: Determines if a technician should be sent for repair
      summary: Calculates costs
      x-ms-summary: Calculates costs
      x-ms-visibility: important
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          description: Hours and capacity used to calculate costs
          x-ms-summary: Hours and capacity
          x-ms-visibility: important
          required: true
          schema:
            type: object
            properties:
              hours:
                description: The amount of effort in hours required to conduct repair
                type: number
                x-ms-summary: Hours
                x-ms-visibility: important
              capacity:
                description: The max output of a turbine in kilowatts
                type: number
                x-ms-summary: Capacity
                x-ms-visibility: important
      responses:
        200:
          description: Message with cost and revenue numbers
          x-ms-summary: Message
          schema:
           type: object
           properties:
            message:
              type: string
              description: Returns Yes or No depending on calculations
              x-ms-summary: Message 
            revenueOpportunity:
              type: string
              description: The revenue opportunity cost
              x-ms-summary: RevenueOpportunity 
            costToFix:
              type: string
              description: The cost in $ to fix the turbine
              x-ms-summary: CostToFix
      security:
        - apikeyQuery: []
definitions: {}
securityDefinitions:
  apikeyQuery:
    type: apiKey
    name: code
    in: query

在此示例中,可以只粘贴已更新的元数据,但请务必了解对默认模板做出的修改类型:

  • 指定 API 生成并使用 JSON 格式的数据。

  • 指定所需的参数,包括其名称和数据类型。

  • 指定成功响应的返回值,包括其名称和数据类型。

  • 为 API 及其操作和参数提供友好的摘要和描述。 这对将要使用此函数的用户很重要。

  • 添加在 Microsoft Flow 和逻辑应用的 UI 中使用的 x-ms-summary 和 x-ms-visibility。 有关详细信息,请参阅 Microsoft Flow 中适用于自定义 API 的 OpenAPI 扩展

Note

我们将安全性定义保留为默认身份验证方法,即 API 密钥。 如果使用不同的身份验证类型,可以更改此定义部分。

有关定义 API 操作的详细信息,请参阅 Open API specification(Open API 规范)。

测试 OpenAPI 定义

使用 API 定义前,最好先在 Azure Functions UI 中对其进行测试。

  1. 在函数的“管理”选项卡上,在“主机密钥”下,复制“默认”密钥。

    复制 API 密钥

    Note

    此密钥用于测试,还可以在使用应用或服务调用 API 时使用。

  2. 返回到 API 定义:“function-demo-energy” > “平台功能” > “API 定义”。

  3. 在右侧窗格中,单击“身份验证”,输入复制的 API 密钥,然后单击“验证”。

    使用 API 密钥进行身份验证

  4. 向下滚动,单击“尝试此操作”。

    尝试此操作

  5. 输入“小时”和“容量”的值。

    输入参数

    请注意,UI 使用了 API 定义中的描述。

  6. 单击“发送请求”,然后单击“优质”选项卡查看输出。

    发送请求

后续步骤

本教程介绍了如何:

  • 在 Azure 中创建一个函数
  • 使用 OpenAPI 工具生成 OpenAPI 定义
  • 修改定义以提供额外的元数据
  • 通过调用函数测试定义