【翻译】Vscode 插件 REST Client 文档翻译

本文使用智谱 GLM 翻译

REST 客户端允许您在 Visual Studio Code 中直接发送 HTTP 请求并查看响应。它消除了测试 REST API 时需要单独工具的需求，使 API 测试变得方便高效。

主要功能

• 发送/取消/重新运行编辑器中的 HTTP 请求，并在单独的窗格中查看带有语法高亮的响应

• 发送 GraphQL 查询并在编辑器中设置 GraphQL 变量

• 发送编辑器中的 cURL 命令并复制 HTTP 请求为 cURL command

• 自动保存和查看/清除请求历史

• 在同一文件中（由 ### 分隔符分隔）编写多个请求

• 直接在面板中查看图像响应

• 仅将原始响应和响应体保存到本地磁盘

• 折叠和展开响应体

• 自定义响应预览中的字体（大小/家族/粗细）

• 预览响应，包括预期部分（仅标题，仅正文，完整响应以及请求和响应）

• 认证支持：

  • 基本认证
  • 摘要认证
  • SSL 客户端证书
  • Azure Active Directory Azure 活动目录
  • 微软身份平台
  • AWS 签名 v4
  • AWS Cognito

• 环境和支持自定义/系统变量

  • 在任何请求（URL、Headers、Body）中使用变量

  • 支持环境、文件、请求和提示自定义变量

  • 交互式分配请求的提示自定义变量

  • 自动完成和悬停支持，适用于环境和文件以及请求自定义变量

  • 诊断支持请求、文件和提示自定义变量

  • 前往请求和文件自定义变量定义支持

  • 查找仅支持文件自定义变量的所有引用

  • 提供系统动态变量

    • {{$guid}}
    • {{$randomInt min max}}
    • {{$timestamp [offset option]}}
    • {{$datetime rfc1123|iso8601 [offset option]}}
    • {{$localDatetime rfc1123|iso8601 [offset option]}}
    • {{$processEnv [%]envVarName}}
    • {{$dotenv [%]variableName}}
    • {{$aadToken [new] [public|cn|de|us|ppe] [<domain|tenantId>] [aud:<domain|tenantId>]}}
    • {{$oidcAccessToken [new] [<clientId:<clientId>] [<callbackPort:<callbackPort>] [authorizeEndpoint:<authorizeEndpoint}] [tokenEndpoint:<tokenEndpoint}] [scopes:<scopes}] [audience:<audience}]}

  • 轻松在设置文件中创建/更新/删除环境和环境变量

  • 文件变量可以引用自定义和系统变量

  • 支持环境切换

  • 支持共享环境以提供在所有环境中可用的变量

• 生成类似 Python ， JavaScript 等语言的 HTTP 请求代码片段！

• 记住 Cookie 以供后续请求

• 代理支持

• 发送 SOAP 请求，以及支持构建 SOAP 信封的片段

• HTTP 语言支持

  • .http 和 .rest 文件扩展名支持
  • 语法高亮（请求和响应）
  • 自动完成方法、URL、头部、自定义/系统变量、MIME 类型等
  • 注释（以 # 或 // 开头的行）支持
  • 支持 json 和 xml 代码缩进，注释快捷键和自动闭合括号
  • 代码片段用于操作如 GET 和 POST
  • 支持导航到符号定义（请求和文件级别自定义变量）在打开的 http 文件中
  • 代码行号支持添加可执行链接以发送请求
  • 折叠/展开请求块

• 支持 Markdown 代码块，使用 http 或 rest

使用

在编辑器中，输入如下简单的 HTTP 请求：

https://example.com/comments/1

或者，您可以遵循包括请求方法、头和主体的标准 RFC 2616。

POST https://example.com/comments HTTP/1.1
content-type: application/json

{
    "name": "sample",
    "time": "Wed, 21 Oct 2015 18:27:50 GMT"
}

发送准备好的请求，您有多种选择。最简单的方法是点击请求上方的 Send Request 链接。如果文件的代码模式设置为 HTTP ，此链接将自动出现。您还可以使用快捷键 Ctrl+Alt+R （macOS 上为 Cmd+Alt+R ），在编辑器中右键单击并从上下文菜单中选择 Send Request ，或者按 F1 并选择/输入 Rest Client: Send Request 。

响应将在 Visual Studio Code 内的单独网页视图中预览。如果您想充分利用在 Visual Studio Code 中搜索、选择或操作的功能，可以通过将 rest-client.previewResponseInUntitledDocument 设置为 true 在无标题文档中预览响应。

当你发起请求时，状态栏将出现一个等待旋转图标，直到收到响应。您可以点击旋转图标来取消请求。一旦收到响应，等待图标将被总持续时间响应大小所取代。将鼠标悬停在状态栏中的总持续时间上，您可以查看响应时间的分解，包括 Socket、DNS、TCP、首字节和下载的详细信息。将鼠标悬停在状态栏中显示的响应大小上，您可以查看头部和正文的响应大小细节分解。

快捷键在 REST 客户端扩展中仅在使用文件语言模式 http 和 plaintext 时可以访问。

选择请求文本

如果您需要在同一文件中存储多个请求并在方便时执行它们，REST 客户端扩展将为您提供支持。通过使用三个或更多连续的 # 符号作为分隔符，您可以在扩展可以识别的请求之间创建分隔。完成此操作后，只需将光标放置在所需请求的分隔符之间，像往常一样发出请求，扩展将无需任何麻烦地将其发送出去。

GET https://example.com/comments/1 HTTP/1.1

###

GET https://example.com/topics/1 HTTP/1.1

###

POST https://example.com/comments HTTP/1.1
content-type: application/json

{
    "name": "sample",
    "time": "Wed, 21 Oct 2015 18:27:50 GMT"
}

REST 客户端扩展还提供了灵活性，您可以在编辑器中使用所选文本发送请求。

安装

按 F1 ，输入 ext install ，然后搜索 rest-client 。

制作请求

请求行

第一個非空選擇行（或未選擇的文件）是請求行。以下是請求行的某些示例：

GET https://example.com/comments/1 HTTP/1.1

GET https://example.com/comments/1

https://example.com/comments/1

如果省略了请求方法，请求将被视为 GET，因此上述请求在解析后是相同的。

查询字符串

您始终可以在请求行中编写查询字符串，例如：

GET https://example.com/comments?page=2&pageSize=10

有时一个请求中可能会有多个查询参数，将所有查询参数放在请求行中难以阅读和修改。因此，我们允许您将查询参数分散到多行（每行一个查询参数），我们将在以 ? 和 & 开始的请求行之后立即解析这些行。

GET https://example.com/comments
    ?page=2
    &pageSize=10

请求头

一旦您编写了请求行，接下来的行直到第一个空行将被解析为请求头。这些头应该遵循标准 field-name: field-value 格式，每行代表一个单独的头。默认情况下，如果您没有明确指定 User-Agent 头， REST Client Extension 将自动添加一个值为 vscode-restclient 的头。但是，如果您想更改默认值，您可以在 rest-client.defaultHeaders 设置中这样做。

以下是请求头示例：

User-Agent: rest-client
Accept-Language: en-GB,en-US;q=0.8,en;q=0.6,zh-CN;q=0.4
Content-Type: application/json

请求体

如果您想提供请求体，只需在请求头之后添加一个空白行，如使用部分中的 POST 示例所示。空白行之后的所有内容都将被视为请求体内容。以下是一些示例：

POST https://example.com/comments HTTP/1.1
Content-Type: application/xml
Authorization: token xxx

<request>
    <name>sample</name>
    <time>Wed, 21 Oct 2015 18:27:50 GMT</time>
</request>

您也可以指定文件路径作为正文，该路径以 < 开头，文件路径（空白字符应保留）可以是绝对路径或相对路径（相对于工作区根目录或当前 http 文件）：

POST https://example.com/comments HTTP/1.1
Content-Type: application/xml
Authorization: token xxx

< C:\Users\Default\Desktop\demo.xml

POST https://example.com/comments HTTP/1.1
Content-Type: application/xml
Authorization: token xxx

< ./demo.xml

如果您想在那个文件中使用变量，您必须使用一个 @ 来确保在引用文件时处理变量（默认编码为 UTF-8）

POST https://example.com/comments HTTP/1.1
Content-Type: application/xml
Authorization: token xxx

<@ ./demo.xml

要覆盖默认编码，只需将其输入到 @ 旁边，如下例所示

POST https://example.com/comments HTTP/1.1
Content-Type: application/xml
Authorization: token xxx

<@latin1 ./demo.xml

当请求体的内容类型为 multipart/form-data 时，请求体的混合格式可能如下所示：

POST https://api.example.com/user/upload
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="text"

title
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="1.png"
Content-Type: image/png

< ./1.png
------WebKitFormBoundary7MA4YWxkTrZu0gW--

当请求体的内容类型为 application/x-www-form-urlencoded 时，您甚至可以将请求体分成多行。每个键值对应占用一行，且以 & 开头：

POST https://api.example.com/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=foo
&password=bar

当鼠标悬停在文档链接上时，您可以 Ctrl+Click （macOS 上为 Cmd+Click ）在新标签页中打开文件。

构建 GraphQL 请求

支持 GraphQL 的 REST 客户端扩展中，您可以使用请求体编写和发送 GraphQL 查询。除此之外，您还可以在请求体中编写 GraphQL 变量。请求体中的 GraphQL 变量部分是可选的，如果需要，您还需要在 GraphQL 查询和变量之间添加一个空行。

您可以通过在标题中添加自定义请求头 X-Request-Type: GraphQL 来指定一个请求为 GraphQL Request 。以下代码说明了这一点：

POST https://api.github.com/graphql
Content-Type: application/json
Authorization: Bearer xxx
X-REQUEST-TYPE: GraphQL

query ($name: String!, $owner: String!) {
  repository(name: $name, owner: $owner) {
    name
    fullName: nameWithOwner
    description
    diskUsage
    forkCount
    stargazers(first: 5) {
        totalCount
        nodes {
            login
            name
        }
    }
    watchers {
        totalCount
    }
  }
}

{
    "name": "vscode-restclient",
    "owner": "Huachao"
}

制作 cURL 请求

我们添加了在 REST 客户端扩展中直接运行 curl 请求的功能。发出请求的命令与原始 HTTP 命令相同。REST 客户端将自动使用指定的解析器解析请求。

REST Client 不完全支持 cURL 的所有选项，因为我们底层使用 request 库发送请求，该库不接受所有 cURL 选项。支持选项如下：

• -X, --request
• -L, --位置, --url
• -H, --header(不支持 @)
• • 我，--头部
• -b, --cookie(不支持 cookie 文件)
• -u, --user(仅支持基本认证)
• -d, --数据, --数据-ascii, --数据-二进制, --数据-原始

复制请求为 cURL

如果您需要快速获取 HTTP 请求的 curl 格式并将其保存到剪贴板，可以使用一个便捷的快捷键。只需按 F1 并选择/输入 Rest Client: Copy Request As cURL 。或者，您可以在编辑器中右键单击并选择 Copy Request As cURL.

取消请求

如果您想取消一个处理请求，请点击等待旋转图标或使用快捷键 Ctrl+Alt+K （macOS 上为 Cmd+Alt+K ），或者按 F1 然后选择/输入 Rest Client: Cancel Request 。

重新运行上一个请求

有时你可能想刷新 API 响应，现在你可以简单地使用快捷键 Ctrl+Alt+L （macOS 上为 Cmd+Alt+L ），或者按 F1 然后选择/输入 Rest Client: Rerun Last Request 来重新运行最后一个请求。

请求历史

每次发送 HTTP 请求时，请求详情（包括方法、URL、头和正文）都会保存到文件中供将来参考。要访问此内容，您可以使用快捷键 Ctrl+Alt+H （macOS 上为 Cmd+Alt+H ），或按 F1 然后选择/输入 Rest Client: Request History 。这将允许您以时间倒序查看最后 50 个请求项，显示每个请求的方法、URL 和请求时间。选择指定的请求历史记录项后，请求详情将显示在临时文件中，您可以查看请求详情或按照前面的步骤再次触发请求。

您也可以通过按 F1 然后选择/输入 Rest Client: Clear Request History 来清除请求历史。

保存完整响应

在响应预览标签页的右上角，我们添加了一个新图标以将最新响应保存到本地文件系统。点击 Save Full Response 图标后，将弹出一个窗口显示保存的响应文件路径。您可以点击 Open 按钮在当前工作区打开保存的响应文件，或点击 Copy Path 将保存的响应路径复制到剪贴板。

保存响应体

另一个图标位于响应预览标签页的右上角是 Save Response Body 按钮，它只会将响应正文保存到本地文件系统。保存文件的扩展名根据响应 MIME 类型设置，例如如果响应头中的 Content-Type 值为 application/json ，则保存的文件将具有扩展名 .json 。您还可以使用 rest-client.mimeAndFileExtensionMapping 设置根据您的需求覆盖 MIME 类型和扩展名映射。

"rest-client.mimeAndFileExtensionMapping": {
    "application/atom+xml": "xml"
}

折叠和展开响应体

在响应的 webview 面板中，点击 More Actions... 按钮后，有两个选项 Fold Response 和 Unfold Response 。有时你可能想折叠或展开整个响应体，这些选项提供了一种直接实现这一目标的方法。

认证

我们支持一些最常用的身份验证方案，如基本认证、摘要认证、SSL 客户端证书、Azure Active Directory（Azure AD）和 AWS 签名 v4。

基本认证

HTTP 基本认证是一种广泛使用的简单用户名/密码认证协议。我们支持三种格式的授权头以使用基本认证。

1. 添加 username:password 的原始值中的 Authorization 头部值。
2. 添加 Authorization 头值的 base64 编码为 username:password .
3. 将 Authorization 头部的值添加到 username 和 password 的原始值中，它们之间由空格分隔。REST 客户端扩展将自动进行 base64 编码。

相应的示例如下，它们是等价的：

GET https://httpbin.org/basic-auth/user/passwd HTTP/1.1
Authorization: Basic user:passwd

和

GET https://httpbin.org/basic-auth/user/passwd HTTP/1.1
Authorization: Basic dXNlcjpwYXNzd2Q=

和

GET https://httpbin.org/basic-auth/user/passwd HTTP/1.1
Authorization: Basic user passwd

摘要认证

HTTP 摘要认证也是一种用户名/密码认证协议，旨在比基本认证稍微安全一些。摘要认证的授权头格式与基本认证类似。您只需设置方案为 Digest ，以及原始用户名和密码即可。

GET https://httpbin.org/digest-auth/auth/user/passwd
Authorization: Digest user passwd

SSL 客户端证书

我们支持 PFX 、 PKCS12 和 PEM 证书。在使用您的证书之前，您需要在设置文件中设置证书路径（绝对路径/相对于工作区/相对于当前 http 文件）以期望的主机名（端口号可选）。对于每个主机，您可以指定 cert 、 key 、 pfx 和 passphrase 密钥。

• cert : 公共 x509 证书路径
• key : 私钥路径
• pfx : PKCS #12 或 PFX 证书的路径
• passphrase : 如果需要，请输入证书的密码短语。如果您的证书格式为 PEM ，您可以在设置文件中添加以下代码片段：

"rest-client.certificates": {
    "localhost:8081": {
        "cert": "/Users/demo/Certificates/client.crt",
        "key": "/Users/demo/Keys/client.key"
    },
    "example.com": {
        "cert": "/Users/demo/Certificates/client.crt",
        "key": "/Users/demo/Keys/client.key"
    }
}

如果您的证书格式为 PFX 或 PKCS12 ，设置代码可以是这样的：

"rest-client.certificates": {
    "localhost:8081": {
        "pfx": "/Users/demo/Certificates/clientcert.p12",
        "passphrase": "123456"
    }
}

Azure Active Directory（Azure AD）

Azure AD 是微软的多租户、基于云的目录和身份管理服务，您可以参考系统变量部分以获取更多详细信息。

微软身份平台（Azure AD V2）

微软身份平台是 Azure Active Directory (Azure AD) 开发者平台的演变。它允许开发者构建可登录所有微软身份并获取调用微软 API（如 Microsoft Graph 或开发者构建的 API）令牌的应用程序。微软身份平台支持 OAuth2 作用域、增量同意和高级功能，如多因素身份验证和条件访问。

AWS 签名 v4

AWS 签名版本 4 用于验证对 AWS 服务的请求。要使用它，您需要将 Authorization 头模式设置为 AWS ，并使用空格分隔提供您的 AWS 凭证：

• <accessId> : AWS 访问密钥 ID
• <accessKey> : AWS 密钥访问密钥
• token:<sessionToken> : AWS 会话令牌 - 仅在临时凭证时需要
• region:<regionName> : AWS 区域 - 仅当无法从 URL 推断区域时才需要
• service:<serviceName> : AWS 服务 - 仅当无法从 URL 推断服务时才需要

GET https://httpbin.org/aws-auth HTTP/1.1
Authorization: AWS <accessId> <accessKey> [token:<sessionToken>] [region:<regionName>] [service:<serviceName>]

AWS Cognito

通过 AWS Cognito 进行身份验证时，您需要将 Authorization 头模式设置为 COGNITO ，并使用空格分隔提供您的 AWS 凭据：

• <Username> : 目标用户的 AWS 用户名
• <Password> : 目标用户的 AWS 密码
• <Region> : Cognito 池的 AWS 区域
• <UserPoolId> : AWS Cognito 用户池 ID
• <ClientId> : AWS Cognito 客户端 ID

GET https://httpbin.org/aws-auth HTTP/1.1
Authorization: COGNITO <Username> <Password> <Region> <UserPoolId> <ClientId>

生成代码片段

一旦您在 REST 客户端扩展中完成请求，您可能希望从源代码中执行相同的请求。我们允许您生成各种语言和库的代码片段，以帮助您实现这一点。一旦您像之前一样准备好请求，使用快捷键 Ctrl+Alt+C （macOS 上为 Cmd+Alt+C ），或在编辑器中右键单击然后选择 Generate Code Snippet 菜单项，或按 F1 然后选择/输入 Rest Client: Generate Code Snippet ，它将弹出语言选择列表以及库列表。选择您想要的代码片段语言/库后，生成的代码片段将在 Visual Studio Code 的单独面板中预览，您可以通过点击标签标题中的 Copy Code Snippet 图标将其复制到剪贴板。

HTTP 语言

添加对 HTTP 请求的语言支持，包括语法高亮、自动完成、代码透镜和注释支持，当在 Visual Studio Code 中编写 HTTP 请求时。默认情况下，语言关联将在两种情况下自动激活：

1. 文件扩展名为 .http 或 .rest
2. 第一行文件遵循 RFC 2616 标准请求行，格式为 Method SP Request-URI SP HTTP-Version

如果您想在其他情况下启用语言关联，只需更改 Visual Studio Code 右下角的语言模式为 HTTP 。

自动完成

当前，将启用以下七个类别的自动完成功能：

1. HTTP 方法
2. HTTP URL 从请求历史
3. HTTP 头部
4. 系统变量
5. 自定义当前环境/文件/请求中的变量
6. MIME 类型用于 Accept 和 Content-Type 头部
7. 认证方案为 Basic 和 Digest

导航到请求文件中的符号

一个单独的 http 文件可能定义了许多请求和文件级别的自定义变量，查找所需的请求/变量会比较困难。我们利用 Visual Studio Code 的“转到符号”功能，通过快捷键 Ctrl+Shift+O （ Cmd+Shift+O 为 macOS）支持导航（转到）到请求/变量，或者直接按 F1 ，输入 @ 。

环境

环境允许您使用变量自定义请求，并且可以轻松切换环境而无需更改 http 文件中的请求。常见用法是为不同的网络服务环境（如 devbox、sandbox 和生产环境）设置不同的配置。我们还支持共享环境（通过特殊环境名称 $shared 识别）以提供一组在所有环境中都有效的变量。您还可以在指定的环境中定义同名变量以覆盖共享环境中的值。当前，活动环境的名称显示在 Visual Studio Code 的右下角，当您点击它时，可以在弹出列表中切换环境。您还可以使用快捷键 Ctrl+Alt+E （macOS 为 Cmd+Alt+E ）或按 F1 然后选择/输入 Rest Client: Switch Environment 来切换环境。

环境及变量直接在 Visual Studio Code 设置文件中定义，因此您可以在任何时候创建/更新/删除环境及变量。如果您不想使用任何环境，可以在环境列表中选择 No Environment 。请注意，如果您选择 No Environment ，共享环境中定义的变量仍然可用。有关环境变量的更多详细信息，请参阅环境变量。

变量

我们支持两种类型的变量，一种是自定义变量，由用户定义，可以进一步分为环境变量、文件变量、提示变量和请求变量，另一种是系统变量，它是一组预定义的变量。

系统变量和自定义变量类型的引用语法有细微差别，前者语法为 {{$SystemVariableName}} ，后者语法为 {{CustomVariableName}} ，自定义变量名称前无需 $ 。不同类型自定义变量的定义语法和位置不同。请注意，当自定义变量使用相同名称时，请求变量解析优先级高于文件变量，文件变量解析优先级高于环境变量。

自定义变量

自定义变量可以覆盖不同的用户场景，并利用环境变量、文件变量和请求变量的优势。环境变量主要用于存储在不同环境中可能变化的值。由于环境变量直接定义在 Visual Studio Code 设置文件中，因此它们可以在不同的 http 文件中引用。文件变量主要用于表示在整个 http 文件中保持不变的值。请求变量用于链式请求场景，这意味着一个请求需要引用同一 http 文件中另一个请求/响应的部分（头部或正文），例如，我们需要从登录响应中动态检索认证令牌，请求变量非常适合这种情况。文件和请求变量都在 http 文件中定义，并且只有文件作用域。

环境变量

对于环境变量，每个环境包含在设置文件中定义的一组键值对，键和值分别是变量名和值。只有定义在所选环境和共享环境中的变量可供您使用。您还可以使用 {{$shared variableName}} 语法在您的活动环境中引用共享环境中的变量。以下是为自定义环境和环境级别变量提供的设置文件示例：

"rest-client.environmentVariables": {
    "$shared": {
        "version": "v1",
        "prodToken": "foo",
        "nonProdToken": "bar"
    },
    "local": {
        "version": "v2",
        "host": "localhost",
        "token": "{{$shared nonProdToken}}",
        "secretKey": "devSecret"
    },
    "production": {
        "host": "example.com",
        "token": "{{$shared prodToken}}",
        "secretKey" : "prodSecret"
    }
}

以下是在 http 文件中上述环境变量的一个示例用法，请注意，如果您切换到本地环境， version 将是 v2，如果您切换到生产环境， version 将是 v1，这是从$shared 环境继承的：

GET https://{{host}}/api/{{version}}comments/1 HTTP/1.1
Authorization: {{token}}

文件变量

对于文件变量，其定义遵循语法 @variableName = variableValue ，它占用一行完整内容。变量名必须不包含任何空格。至于变量值，它可以由任何字符组成，甚至允许包含空白字符（前导和尾随空白将被删除）。如果您想保留一些特殊字符，如换行符，可以使用反斜杠 `` 进行转义，例如 \n 。文件变量值甚至可以包含对其他所有类型变量的引用。例如，您可以创建一个具有其他请求变量值的文件变量，如 @token = {{loginAPI.response.body.token}} 。在引用文件变量时，您可以使用百分号 % 对值进行百分号编码。

文件变量只能在单独的请求块中定义，该块仅包含变量定义，以及在任何请求 URL 之前定义请求变量，变量定义和请求 URL 之间需要额外的空行。然而，无论在 http 文件中的哪个位置定义文件变量，都可以在任何整个文件的请求中引用它们。对于文件变量，您还可以从一些 Visual Studio Code 功能中受益，如转到定义和查找所有引用。以下是 http 文件中文件变量定义和引用的示例。

@hostname = api.example.com
@port = 8080
@host = {{hostname}}:{{port}}
@contentType = application/json
@createdAt = {{$datetime iso8601}}
@modifiedBy = {{$processEnv USERNAME}}

###

@name = Strunk & White

GET https://{{host}}/authors/{{%name}} HTTP/1.1

###

PATCH https://{{host}}/authors/{{%name}} HTTP/1.1
Content-Type: {{contentType}}

{
    "content": "foo bar",
    "created_at": "{{createdAt}}",
    "modified_by": "{{modifiedBy}}"
}

提示变量

使用提示变量，用户可以在发送请求时输入要使用的变量。这提供了在不修改 http 文件的情况下更改大多数动态变量的灵活性。用户可以指定多个提示变量。提示变量的定义语法类似于在所需请求 URL 之前添加语法，使用以下语法 // @prompt {var1} 或 # @prompt {var1} 。也可以使用 // @prompt {var1} {description} 或 # @prompt {var1} {description} 分配变量描述，这将弹出一个带有所需描述信息的输入提示框。

用户输入将在以下变量名称之一时被隐藏： password ， Password ， PASSWORD ， passwd ， Passwd ， PASSWD ， pass ， Pass ， PASS 。

参考语法与其他相同，遵循 {{var}} 。提示变量将覆盖任何先前分配的变量，并且永远不会存储以供其他请求使用。

@hostname = api.example.com
@port = 8080
@host = {{hostname}}:{{port}}
@contentType = application/json

###
# @prompt username
# @prompt refCode Your reference code display on webpage
# @prompt otp Your one-time password in your mailbox
POST https://{{host}}/verify-otp/{{refCode}} HTTP/1.1
Content-Type: {{contentType}}

{
    "username": "{{username}}",
    "otp": "{{otp}}"
}

请求变量

请求变量在某些方面类似于文件变量，例如作用域和定义位置。然而，它们有一些明显的区别。请求变量的定义语法就像单行注释，在所需请求 URL 之前跟随 // @name requestName 或 # @name requestName 。你可以将请求变量视为将名称元数据附加到底层请求上，这种请求可以通过命名请求调用，而普通请求可以通过匿名请求调用。其他请求可以使用 requestName 作为标识符来引用命名请求的预期部分或其最新响应。请注意，如果你想引用命名请求的响应，你需要手动触发命名请求以检索其响应，否则将发送变量引用的纯文本，如 {{requestName.response.body.$.id}} 。

请求变量的引用语法比其他类型的自定义变量要复杂一些。请求变量引用语法遵循 {{requestName.(response|request).(body|headers).(*|JSONPath|XPath|Header Name)}} 。您有两个引用部分选择：响应或请求：正文和头部。对于正文部分，您可以使用 * 来引用完整的响应正文，对于 JSON 和 XML 响应，您可以使用 JSONPath 和 XPath 提取特定的属性或属性。例如，如果 JSON 响应返回正文 {"id": "mock"} ，您可以将 JSONPath 部分设置为 $.id 来引用 id。对于头部部分，您可以指定要提取头部值的头部名称。此外，头部名称不区分大小写。

如果无法解析 body 的 JSONPath 或 XPath，或者 headers 的 Header 名称，则将发送变量引用的纯文本。在这种情况下，将显示诊断信息以帮助您检查。您还可以将鼠标悬停在请求变量上以查看实际解析的值。

以下是 http 文件中请求变量定义和引用的示例。

@baseUrl = https://example.com/api

# @name login
POST {{baseUrl}}/api/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=foo&password=bar

###

@authToken = {{login.response.headers.X-AuthToken}}

# @name createComment
POST {{baseUrl}}/comments HTTP/1.1
Authorization: {{authToken}}
Content-Type: application/json

{
    "content": "fake content"
}

###

@commentId = {{createComment.response.body.$.id}}

# @name getCreatedComment
GET {{baseUrl}}/comments/{{commentId}} HTTP/1.1
Authorization: {{authToken}}

###

# @name getReplies
GET {{baseUrl}}/comments/{{commentId}}/replies HTTP/1.1
Accept: application/xml

###

# @name getFirstReply
GET {{baseUrl}}/comments/{{commentId}}/replies/{{getReplies.response.body.//reply[1]/@id}}

系统变量

系统变量提供一组预定义的变量，可以在请求的任何部分（URL/头部/正文）中使用，格式为 {{$variableName}} 。目前，我们提供了一些动态变量，您可以在请求中使用。变量名称区分大小写。

• {{$aadToken [new] [public|cn|de|us|ppe] [<domain|tenantId>] [aud:<domain|tenantId>]}} : 根据以下选项添加基于 Azure Active Directory 的令牌（必须按顺序指定）：

  new : 可选。指定 new 以强制重新认证并获取指定目录的新令牌。默认：从内存缓存中重用指定目录的先前令牌。已过期的令牌会自动刷新。（使用 F1 > Rest Client: Clear Azure AD Token Cache 或重启 Visual Studio Code 以清除缓存。）

  public|cn|de|us|ppe : 可选。指定顶级域名（TLD）以获取指定政府云的令牌， public 用于公共云，或 ppe 用于内部测试。默认：REST 端点的 TLD； public 如果无效。

  <domain|tenantId> : 可选。用于登录的目录或租户 ID。默认：从下拉菜单中选择一个目录或按 Esc 使用主目录（ common 用于 Microsoft 帐户）。

  aud:<domain|tenantId> : 可选。目标 Azure AD 应用程序 ID（即客户端 ID）或应为此令牌创建域（即受众或资源）。默认：REST 端点的域。

• {{$aadV2Token [new] [AzureCloud|AzureChinaCloud|AzureUSGovernment|ppe] [appOnly ][scopes:<scope[,]>] [tenantid:<domain|tenantId>] [clientid:<clientId>]}} : 根据以下选项添加基于 Azure Active Directory 的令牌（必须按顺序指定）：

  new : 可选。指定 new 以强制重新认证并获取指定目录的新令牌。默认：重用内存缓存中指定 tenantId 和 clientId 的先前令牌。已过期的令牌将自动刷新。（重启 Visual Studio Code 以清除缓存。）

  AzureCloud|AzureChinaCloud|AzureUSGovernment|ppe : 可选。指定主权云（或 ppe 用于内部测试）以获取令牌。默认：'AzureCloud'。

  appOnly : 可选。指定 appOnly 使用 make 以客户端凭据流获取令牌。 aadV2ClientSecret 和 aadV2AppUri 必须作为 REST 客户端环境变量提供。 aadV2ClientId 、 aadV2TenantId 和 aadV2Cloud 也可以通过环境变量可选提供。 aadV2ClientId 在环境中仅用于 appOnly 调用。

  scopes:<scope[,]> : 可选。用逗号分隔的必须获得同意的权限列表，以允许调用成功。不适用于 appOnly 调用。 aadV2Scopes 可通过环境变量可选提供。

  tenantId:<domain|tenantId> : 可选。租户登录的域或租户 ID。（ common 用于从登录中确定租户）。

  clientId:<clientid> : 可选。用于获取令牌的应用程序注册标识符。默认使用为该插件专门创建的应用程序注册。

• {{$oidcAccessToken [new] [<clientId:<clientId>] [<callbackPort:<callbackPort>] [authorizeEndpoint:<authorizeEndpoint}] [tokenEndpoint:<tokenEndpoint}] [scopes:<scopes}] [audience:<audience}]} : 根据以下选项添加基于 Oidc 身份服务器令牌（必须按顺序指定）：

  new : 可选。指定 new 以强制重新认证并获取客户端的新令牌。默认：从内存缓存中重用 clientId 的先前令牌。已过期的令牌会自动刷新。（重启 Visual Studio Code 以清除缓存。）

  clientId:<clientid> : 可选。使用以获取令牌的应用程序注册标识符。

  callbackPort:<callbackPort> : 可选。用于本地回调服务器的端口。默认：7777（随机端口）。

  authorizeEndpoint:<authorizeEndpoint> : 要使用的授权端点。

  tokenEndpoint:<tokenEndpoint> : 要使用的令牌端点。

  scopes:<scope[,]> : 可选。用逗号分隔的必须获得同意的权限列表，允许调用成功。

  audience:<audience> : 可选。

• {{$guid}} : 添加 RFC 4122 v4 UUID

• {{$processEnv [%]envVarName}} ：允许将本地机器环境变量解析为字符串值。典型用例是用于不希望提交到源控制的密钥。例如：在 .bashrc 或类似的 Windows 上定义 shell 环境变量

  export DEVSECRET="XlII3JUaEZldVg="
  export PRODSECRET="qMTkleUgjclRoRmV1WA=="
  export USERNAME="sameUsernameInDevAndProd"
  

  并且使用扩展设置环境变量。

  "rest-client.environmentVariables": {
      "$shared": {
          "version": "v1"
      },
      "local": {
          "version": "v2",
          "host": "localhost",
          "secretKey": "DEVSECRET"
      },
      "production": {
          "host": "example.com",
          "secretKey" : "PRODSECRET"
      }
  }
  

  您可以直接在脚本中引用键（例如 PRODSECRET ），例如在生产环境中运行时

  # Lookup PRODSECRET from local machine environment
  GET https://{{host}}/{{version}}/values/item1?user={{$processEnv USERNAME}}
  Authorization: {{$processEnv PRODSECRET}}
  

  或者，它可以重写为通过扩展环境设置（例如 %secretKey ）间接引用键，使用可选的 % 修饰符使其环境无关。

  # Use secretKey from extension environment settings to determine which local machine environment variable to use
  GET https://{{host}}/{{version}}/values/item1?user={{$processEnv USERNAME}}
  Authorization: {{$processEnv %secretKey}}
  

  envVarName : 强制性。指定本地机器环境变量

  % : 可选。如果指定，将 envVarName 作为扩展设置环境变量处理，并使用该变量的值进行查找。

• {{$dotenv [%]variableName}} ：返回存储在您的 .env 文件中的环境值，该文件位于您的 .http 文件相同的目录中。

• {{$randomInt min max}} : 返回介于 min（包含）和 max（不包含）之间的随机整数

• {{$timestamp [offset option]}} : 添加当前 UTC 时间戳。您甚至可以根据当前时间指定任何日期时间，格式为 {{$timestamp number option}} ，例如，要表示 3 小时前，只需 {{$timestamp -3 h}} ；要表示后天，只需 {{$timestamp 2 d}} 。

• {{$datetime rfc1123|iso8601|"custom format"|'custom format' [offset option]}} : 添加 ISO8601、RFC1123 或自定义显示格式的日期时间字符串。您甚至可以指定类似于 timestamp 的相对于当前日期的日期时间，例如： {{$datetime iso8601 1 y}} 以表示 ISO8601 格式的未来一年。如果指定自定义格式，请用单引号或双引号括起来，例如： {{$datetime "DD-MM-YYYY" 1 y}} 。日期使用 Day.js 格式化，有关格式字符串的信息请参阅此处。

• {{$localDatetime rfc1123|iso8601|"custom format"|'custom format' [offset option]}} : 与 $datetime 类似，但 $localDatetime 返回您本地时区的时间字符串。

您可以在 timestamp 和 datetime 中指定的偏移量选项有：

选项	描述
y	年
M	月份
w	周
d	天
h	小时
m	分钟
s	第二
ms	毫秒

以下是使用系统变量的示例：

POST https://api.example.com/comments HTTP/1.1
Content-Type: application/xml
Date: {{$datetime rfc1123}}

{
    "user_name": "{{$dotenv USERNAME}}",
    "request_id": "{{$guid}}",
    "updated_at": "{{$timestamp}}",
    "created_at": "{{$timestamp -1 d}}",
    "review_count": "{{$randomInt 5 200}}",
    "custom_date": "{{$datetime 'YYYY-MM-DD'}}",
    "local_custom_date": "{{$localDatetime 'YYYY-MM-DD'}}"
}

更多关于 aadToken （Azure Active Directory Token）的详细信息可以在 Wiki 上找到

自定义响应预览

REST 客户端扩展添加了控制响应预览中使用的字体家族、大小和粗细的能力。

默认情况下，REST 客户端扩展仅在预览面板中预览完整响应（状态行、头部和正文）。您可以通过 rest-client.previewOption 设置来控制应预览哪一部分：

选项	描述
完整	默认。完整响应已预览
头文件	仅预览响应头（包括状态行）
body	仅预览响应体
交换	预览整个 HTTP 交换（请求和响应）

设置

• rest-client.followredirect : 跟踪 HTTP 3xx 响应作为重定向。 (默认为 true)
• 如果请求头中省略了特定头，这些头将作为每个请求的头添加。（默认为 { "User-Agent": "vscode-restclient", "Accept-Encoding": "gzip" } ）
• rest-client.timeoutinmilliseconds : 超时（毫秒）。0 表示无限。默认为 0
• rest-client.showResponseInDifferentTab : 在不同标签页中显示响应。（默认为 false）
• rest-client.requestNameAsResponseTabTitle : 将请求名称显示为响应标签页标题。仅在使用 HTML 视图时有效，如果没有指定请求名称，则默认为“响应”。（默认为 false）
• rest-client.rememberCookiesForSubsequentRequests : 将响应中的 Set-Cookie 头部中的 cookies 保存并用于后续请求。（默认为 true）
• rest-client.enableTelemetry : 发送匿名使用数据。（默认为 false）
• rest-client.excludeHostsForProxy : 使用代理设置时排除的主机。（默认为[]）
• rest-client.fontSize : 控制响应预览中使用的像素字体大小。（默认为 13）
• rest-client.fontFamily : 控制响应预览中使用的字体族。（默认为 Menlo, Monaco, Consolas, “Droid Sans Mono”， “Courier New”，等宽， “Droid Sans Fallback”）
• rest-client.fontWeight : 控制响应预览中使用的字体粗细。（默认为正常）
• rest-client.environmentVariables ：设置属于它的环境和自定义变量（例如， {"production": {"host": "api.example.com"}, "sandbox":{"host":"sandbox.api.example.com"}} ）。（默认为{}）
• rest-client.mimeAndFileExtensionMapping : 设置保存响应体的自定义 MIME 类型和文件扩展名映射。（默认为{}）
• rest-client.previewResponseInUntitledDocument ：如果设置为 true，则在无标题文档中预览响应，否则在 HTML 视图中显示。（默认为 false）
• rest-client.certificates : 不同主机的证书路径。路径可以是绝对路径或相对路径（相对于工作区或当前 http 文件）。（默认为{}）
• rest-client.suppressResponseBodyContentTypeValidationWarning : 禁用响应体内容类型验证。（默认为 false）
• rest-client.previewOption : 响应预览输出选项。选项详情如上所述。（默认为全部）
• rest-client.disableHighlightResponseBodyForLargeResponse : 控制是否突出显示大于由 rest-client.largeResponseSizeLimitInMB 指定限制大小的响应体。（默认为 true）
• rest-client.disableAddingHrefLinkForLargeResponse : 控制是否在预览响应中为大于由 rest-client.largeResponseSizeLimitInMB 指定限制大小的响应添加 href 链接。 (默认为 true)
• rest-client.largeResponseBodySizeLimitInMB : 设置响应体大小阈值（以 MB 为单位），以确定响应是否为所谓的“大响应”，仅在 rest-client.disableHighlightResponseBodyForLargeResponse 和/或 rest-client.disableAddingHrefLinkForLargeResponse 设置为 true 时使用。（默认为 5）
• rest-client.previewColumn : 响应预览列选项。'current' 用于在当前请求文件的列中预览。'beside' 用于在当前活动列的旁边预览，侧方向取决于 workbench.editor.openSideBySideDirection 设置，可以是右侧或当前编辑列下方。（默认为 beside）
• rest-client.previewResponsePanelTakeFocus : 预览响应面板在收到响应后将获得焦点。（默认为 True）
• rest-client.formParamEncodingStrategy : x-www-form-urlencoded 请求体参数编码策略。 automatic 用于自动检测编码，并在必要时进行编码。 never 用于将提供的请求体按原样处理，不应用编码。 always 仅用于 automatic 选项无法正常工作时的情况，例如，某些特殊字符（ + ）未正确编码。（默认为自动）
• rest-client.addRequestBodyLineIndentationAroundBrackets : 在按下回车键时，在请求体中的括号（ {} 、 <> 、 [] ）周围添加行缩进。（默认为 true）
• rest-client.decodeEscapedUnicodeCharacters : 解码响应体中的转义 Unicode 字符。 (默认为 false)
• rest-client.logLevel : REST 输出面板中日志的详细程度。（默认为错误）
• rest-client.enableSendRequestCodeLens : 启用/禁用在请求文件中发送请求 CodeLens。 (默认为 true)
• rest-client.enableCustomVariableReferencesCodeLens : 启用/禁用请求文件中自定义变量引用 CodeLens。 (默认为 true)
• rest-client.useContentDispositionFilename : 使用 filename= 从 'content-disposition' 头部（如果可用），在保存响应体时确定输出文件名。（默认为 true）

Rest 客户端扩展尊重为 Visual Studio Code 设置的代理设置（ http.proxy 和 http.proxyStrictSSL ）。仅支持 HTTP 和 HTTPS 代理。

按请求设置

REST 客户端扩展还支持为每个独立请求设置请求级别的设置。语法与请求名称定义类似， # @settingName [settingValue] ，包括一个必需的设置名称以及可选的设置值。以下列出了可用的设置：

姓名	语法	描述
注意	# @note	用于请求确认，尤其是对于关键请求
无重定向	# @no-redirect	不要将 3XX 响应作为重定向遵循
无 cookie-jar	# @no-cookie-jar	不要在饼干罐里保存饼干

所有上述的 # 都可以替换为 //