【译】HTTP 文件更新了请求变量

许多用户都要求在 Visual Studio 的 HTTP 文件中添加对请求变量的支持。使用请求变量，您可以发送 HTTP 请求，然后在从 HTTP 文件发送的任何后续请求中使用响应或请求中的数据。我们还添加了对共享环境 $shared 的支持，它使您能够在不同的环境中共享变量。在这篇文章中，我们将概述对请求变量等新添加的支持。本文中列出的所有功能都包含在 Visual Studio 2022 17.12+ 中。

请求变量

在使用 API 时，通常会从终结点获取一个值，然后在后续请求中使用该值。这可以通过使用请求变量来实现。我们有请求变量的文档，但我们也会在这里讨论所有内容。使用请求变量的一个更常见的场景是，当您调用终结点对 API 进行身份验证并获得可用于未来请求的令牌时。下面的示例请求是 David Fowler 的 TodoApi 示例。该 API 有一个终结点，您可以通过提供用户名和密码来创建一个新用户。这是我们正在发出请求的终结点。

@username = bloguser
# login and save the response as "login"
# @name login
POST {{TodoApi_HostAddress}}/users/token
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
###

在这种情况下，用户名是在 HTTP 文件中定义的，但密码是使用 HTTP Environments 安全地存储的。下面的请求是发送给 /users/token 终结点的，我们将用户名和密码作为 HTTP 请求主体的一部分传入。使其成为请求变量（有时也称为命名请求），特殊之处在于注释上方的那一行。

# @name login

在 Visual Studio 中发送此请求后，您可以从响应或请求中获取值。在下面的代码片段中，您可以看到我们如何使用登录中的请求变量来访问在提交响应时作为响应的一部分返回的令牌。登录的响应包含一个 token。现在我们已经登录了，我们可以用下面的请求创建一个 TODO 项。

# Create a TODO item
# @name todo1
POST {{TodoApi_HostAddress}}/todos
Authorization: Bearer {{login.response.body.$.token}}
Content-Type: application/json

{
  "title": "Write blog post"
}
###

在此请求中，我们提取 token 值并使用它来指定 Authorization 头的值。语法为 {{login.response.body.$.token}}。让我们仔细看看语法。

{{login.response.body.$.token}}

下面的表格总结了使用来自请求变量的值的语法：

|-----------------------------|----------------------------------------------------------------------------------------------------------|
| 元素 | 描述 |
| requestVarName | 被引用的请求变量。 |
| response|request | 是否从响应或请求中提取值。 |
| body|headers | 是否从请求或响应的报头或正文中提取值 |
| *|JSONPath|XPath|Header | 计算表达式，用于结果提取 对于返回 JSON 主体的请求，使用 JSONPath 表达式。 对于返回 XML 主体的请求，使用 XPath。 * 将返回整个结果。 当从 header 中提取时不能使用*。 |

对于上面的示例请求，我们从响应中提取令牌，并将其作为请求的标头传递给 /todos 终结点。发送此请求后，返回的结果如下所示：

{
  "id": 36,
  "title": "Write blog post",
  "isComplete": false
}

现在我们已经创建了一个 TODO 项目，我们可以用下面的请求更新该项目。如果您注意到上面的请求声明了一个名为 todo1 的请求变量，那么我们可以使用它来引用响应或请求中的值。让我们更新标题，在当前标题的末尾添加"today"。下面的请求将更新 TODO 项。我们将使用 PUT，因为这是对现有项的更新。

PUT {{TodoApi_HostAddress}}/todos/{{todo1.response.body.$.id}}
Authorization: Bearer {{login.response.body.$.token}}
Content-Type: application/json

{
  "id": {{todo1.response.body.$.id}},
  "title": "{{todo1.response.body.$.title}} today",
  "isComplete": {{todo1.response.body.$.isComplete}}
}
###

在这个请求中，我们使用来自原始 todo1 请求的数据填充 PUT 请求的主体。注意，title 属性将"today"附加到现有标题的末尾。发送此请求后，结果为：

{
  "id": 36,
  "title": "Write blog post today",
  "isComplete": false
}

在这里，您可以看到博客文章的标题已成功更新。在这些示例中，我展示了如何处理"扁平"的 JSON 结果，但是您可以使用任何 JSONPath 表达式从响应或请求体中提取数据。如果终结点返回 XML，请使用 XPath 表达式而不是 JSONPath。让我们继续讨论对 $shared 的支持。

$shared

在使用 HTTP 环境时，您可以为 HTTP 请求定义多个不同的环境。例如，您可以创建一个引用本地运行的 API 的开发环境，当您想要向远程测试环境发送请求时创建一个测试环境。在这些情况下，您可能希望声明一个对所有环境都可用的变量。这正是新的 $shared 环境所要做的。HTTP 环境定义在一个名为 http-client.env. json 或 http-client.env.json.user 的文件中。如果您创建了一个名为 $shared 的环境，那么这些变量将在任何环境中可用。如果在 $shared 和标准环境中都声明了一个变量，那么在标准环境中定义的值将优先。下面是一个示例 HTTP 环境文件，其中包含一个 $shared 环境和两个标准环境。

{
  "$shared": {
    "message": "Default msg from Shared",
    "username": "httpfile-user",
    "hosturl": "http://example.com/api/sample"
  },
  "dev": {
    "hosturl": "http://localhost:5000/api/sample"
  },
  "prod": {
    "message": "Message from prod environment"
  }
}

这是一个非常基本的 HTTP 环境文件，除了 $shared 之外，我们还定义了 dev 和 prod 环境。在 dev 环境中，hosturl 的值已被定制为指向localhost，而 prod 环境已自定义 message 的值。为了说明这是如何工作的，我们将使用第三方开源网站 httpbin.org。对于 API 开发人员来说，httpbin.org 是一个很好的工具。我们将创建一个 HTTP 文件，向 httpbin.org 发出请求，并让它返回所提供的值。我们将使用 /headers 终结点，这样 httpbin 就会回显我们发送给它的报头。以下是我们将发送的请求：

GET https://httpbin.org/headers
X-Message: {{message}}
X-User: {{username}}
X-Hosturl: {{hosturl}}

###

此请求将使用发送到 httpbin.org 的请求中 HTTP 环境中定义的变量。提醒一下，您可以在 HTTP 文件编辑器右上方的下拉菜单中选择环境。我将环境设置为 dev，来自 httpbin.org 的结果如下所示：

{
  "headers": {
    "X-Hosturl": "http://localhost:5000/api/sample",
    "X-Message": "Default msg from Shared",
    "X-User": "httpfile-user"
  }
}

在响应中，我删除了一些无关的标题。我们可以看到，这些值正在按预期填充。hosturl 的值是在 dev 环境中指定的 localhost，其他值来自 $shared。当我们将环境切换到 prod 并发送相同的请求时，响应如下所示：

{
  "headers": {
    "X-Hosturl": "http://example.com/api/sample",
    "X-Message": "Message from prod environment",
    "X-User": "httpfile-user"
  }
}

hosturl 和 message 的值都已更改。hosturl 和 username 的值来自 $shared，message 来自 prod 环境中提供的值。如果您在没有选择环境的情况下发送请求，则 $shared 中的值将可用。现在我们已经介绍了对 $shared 的新支持，现在我们将结束这篇博文。

小结

在这篇文章中，我们介绍了 HTTP 文件的两个新特性，请求变量和 HTTP 环境中的 $shared。有了请求变量的支持，您现在可以创建"链式"请求，它从以前的请求中获取值。这将使您能够以比以前更实际的方式练习API。此外，使用 $shared，您现在可以跨环境共享变量，从而使您更容易使用 HTTP 环境。如果您不熟悉 HTTP 文件，请查看文档以获取更多信息。

这次更新灵感来自于像您这样的用户的反馈。您可以通过开发者社区与我们分享反馈：通过报告错误或问题，并分享您对新功能或改进现有功能的建议。

原文连接：https://devblogs.microsoft.com/visualstudio/http-file-updates-for-request-variables-and-more/