Compartilhar via


Testar APIs Web com HttpRepl

O HTTP REPL (Read-Eval-Print Loop) é:

  • Uma ferramenta de linha de comando leve e multiplataforma compatível com todos os recursos compatíveis com o .NET Core.
  • Usado para fazer solicitações HTTP a fim de testar as APIs Web do ASP.NET Core (e as APIs Web não pertencentes ao ASP.NET Core) e exibir os resultados.
  • Capaz de testar APIs Web hospedadas em qualquer ambiente, inclusive no localhost e no Serviço de Aplicativo do Azure.

Os verbos HTTP a seguir são compatíveis:

Para acompanhar, exiba ou baixe a API Web de exemplo do ASP.NET Core (como baixar).

Pré-requisitos

Instalação

Para instalar o HttpRepl, execute o seguinte comando:

dotnet tool install -g Microsoft.dotnet-httprepl

Uma ferramenta global do .NET Core é instalada pelo pacote do NuGet Microsoft.dotnet-httprepl.

Observação

Por padrão, a arquitetura dos binários do .NET a serem instalados representa a arquitetura do SO sendo executado no momento. Para especificar uma arquitetura de SO diferente, consulte instalação da ferramenta dotnet, opção --arch. Para obter mais informações, confira o problema dotnet/AspNetCore.Docs #29262 do GitHub.

No macOS, atualize o caminho:

export PATH="$HOME/.dotnet/tools:$PATH"

Uso

Após a instalação da ferramenta, execute o seguinte comando para iniciar o HttpRepl:

httprepl

Para exibir os comandos HttpRepl disponíveis, execute um dos seguintes comandos:

httprepl -h
httprepl --help

É exibida a saída a seguir:

Usage:
  httprepl [<BASE_ADDRESS>] [options]

Arguments:
  <BASE_ADDRESS> - The initial base address for the REPL.

Options:
  -h|--help - Show help information.

Once the REPL starts, these commands are valid:

Setup Commands:
Use these commands to configure the tool for your API server

connect        Configures the directory structure and base address of the api server
set header     Sets or clears a header for all requests. e.g. `set header content-type application/json`

HTTP Commands:
Use these commands to execute requests against your application.

GET            get - Issues a GET request
POST           post - Issues a POST request
PUT            put - Issues a PUT request
DELETE         delete - Issues a DELETE request
PATCH          patch - Issues a PATCH request
HEAD           head - Issues a HEAD request
OPTIONS        options - Issues a OPTIONS request

Navigation Commands:
The REPL allows you to navigate your URL space and focus on specific APIs that you are working on.

ls             Show all endpoints for the current path
cd             Append the given directory to the currently selected path, or move up a path when using `cd ..`

Shell Commands:
Use these commands to interact with the REPL shell.

clear          Removes all text from the shell
echo [on/off]  Turns request echoing on or off, show the request that was made when using request commands
exit           Exit the shell

REPL Customization Commands:
Use these commands to customize the REPL behavior.

pref [get/set] Allows viewing or changing preferences, e.g. 'pref set editor.command.default 'C:\\Program Files\\Microsoft VS Code\\Code.exe'`
run            Runs the script at the given path. A script is a set of commands that can be typed with one command per line
ui             Displays the Swagger UI page, if available, in the default browser

Use `help <COMMAND>` for more detail on an individual command. e.g. `help get`.
For detailed tool info, see https://aka.ms/http-repl-doc.

O HttpRepl oferece preenchimento de comando. Pressionar a tecla Tab itera na lista de comandos que completam os caracteres ou o ponto de extremidade da API que você digitou. As seções a seguir descrevem os comandos da CLI disponíveis.

Conectar-se à API Web

Conecte-se à uma API Web executando o seguinte comando:

httprepl <ROOT URI>

<ROOT URI> é o URI de base para a API Web. Por exemplo:

httprepl https://localhost:5001

Outra opção é executar o seguinte comando a qualquer momento enquanto HttpRepl estiver em execução:

connect <ROOT URI>

Por exemplo:

(Disconnected)> connect https://localhost:5001

Apontar manualmente para a descrição do OpenAPI da API Web

O comando connect acima tentará localizar automaticamente a descrição do OpenAPI. Se isso não for possível por algum motivo, você poderá especificar o URI da descrição do OpenAPI para a API Web usando a opção --openapi:

connect <ROOT URI> --openapi <OPENAPI DESCRIPTION ADDRESS>

Por exemplo:

(Disconnected)> connect https://localhost:5001 --openapi /swagger/v1/swagger.json

Habilitar a saída detalhada para obter detalhes sobre pesquisa, análise e validação de descrição do OpenAPI

Especificar a opção --verbose com o comando connect produzirá mais detalhes quando a ferramenta pesquisar a descrição do OpenAPI, analisar e validá-la.

connect <ROOT URI> --verbose

Por exemplo:

(Disconnected)> connect https://localhost:5001 --verbose
Checking https://localhost:5001/swagger.json... 404 NotFound
Checking https://localhost:5001/swagger/v1/swagger.json... 404 NotFound
Checking https://localhost:5001/openapi.json... Found
Parsing... Successful (with warnings)
The field 'info' in 'document' object is REQUIRED [#/info]
The field 'paths' in 'document' object is REQUIRED [#/paths]

Exibir os pontos de extremidade disponíveis

Para listar os diferentes pontos de extremidade (controladores) no caminho atual do endereço da API Web, execute os comandos ls ou dir:

https://localhost:5001/> ls

O seguinte formato de saída será exibido:

.        []
Fruits   [get|post]
People   [get|post]

https://localhost:5001/>

A saída anterior indica que há dois controladores disponíveis: Fruits e People. Ambos os controladores são compatíveis com operações HTTP GET e POST sem parâmetro.

Navegar em um controlador específico revela mais detalhes. Por exemplo, a saída do seguinte comando mostra que o controlador Fruits também é compatível com as operações HTTP GET, PUT e DELETE. Cada uma dessas operações espera um parâmetro id na rota:

https://localhost:5001/fruits> ls
.      [get|post]
..     []
{id}   [get|put|delete]

https://localhost:5001/fruits>

Outra opção é executar o comando ui para abrir a página da interface do usuário do Swagger da API Web em um navegador. Por exemplo:

https://localhost:5001/> ui

Para navegar até um ponto de extremidade diferente na API Web, execute o comando cd:

https://localhost:5001/> cd people

O caminho após o comando cd não diferencia maiúsculas de minúsculas. O seguinte formato de saída será exibido:

/people    [get|post]

https://localhost:5001/people>

Personalizar o HttpRepl

As cores padrão do HttpRepl podem ser personalizadas. Além disso, um editor de texto padrão pode ser definido. As preferências de HttpRepl são persistidas em toda a sessão atual e serão respeitadas nas sessões futuras. Depois de modificadas, as preferências são armazenadas no seguinte arquivo:

%HOME%/.httpreplprefs

O arquivo .httpreplprefs é carregado na inicialização e suas alterações não são monitoradas no runtime. As modificações manuais no arquivo entram em vigor somente após a reinicialização da ferramenta.

Exibir as configurações

Para exibir as configurações disponíveis, execute o comando pref get. Por exemplo:

https://localhost:5001/> pref get

O comando anterior exibe os pares chave-valor disponíveis:

colors.json=Green
colors.json.arrayBrace=BoldCyan
colors.json.comma=BoldYellow
colors.json.name=BoldMagenta
colors.json.nameSeparator=BoldWhite
colors.json.objectBrace=Cyan
colors.protocol=BoldGreen
colors.status=BoldYellow

Definir preferências de cores

No momento, as cores das respostas só são compatíveis com JSON. Para personalizar a cor padrão da ferramenta HttpRepl, localize a chave correspondente à cor a ser alterada. Para ver instruções sobre como localizar as chaves, confira a seção Exibir as configurações. Por exemplo, altere o valor da chave colors.json de Green para White, desta forma:

https://localhost:5001/people> pref set colors.json White

Somente as cores permitidas podem ser usadas. As solicitações HTTP subsequentes exibem a saída com a nova cor.

Quando chaves de cor específicas não estão definidas, mais chaves genéricas são consideradas. Para demonstrar esse comportamento de fallback, considere o seguinte exemplo:

  • Se colors.json.name não tiver um valor, colors.json.string será usado.
  • Se colors.json.string não tiver um valor, colors.json.literal será usado.
  • Se colors.json.literal não tiver um valor, colors.json será usado.
  • Se colors.json não tiver um valor, a cor de texto padrão do shell de comando (AllowedColors.None) será usada.

Definir o tamanho do recuo

A personalização do tamanho do recuo da resposta só é compatível com JSON. O tamanho padrão é dois espaços. Por exemplo:

[
  {
    "id": 1,
    "name": "Apple"
  },
  {
    "id": 2,
    "name": "Orange"
  },
  {
    "id": 3,
    "name": "Strawberry"
  }
]

Para alterar o tamanho padrão, defina a chave formatting.json.indentSize. Por exemplo, para sempre usar quatro espaços:

pref set formatting.json.indentSize 4

As respostas subsequentes respeitarão a configuração de quatro espaços:

[
    {
        "id": 1,
        "name": "Apple"
    },
    {
        "id": 2,
        "name": "Orange"
    },
    {
        "id": 3,
        "name": "Strawberry"
    }
]

Definir o editor de texto padrão

Por padrão, o HttpRepl não tem um editor de texto configurado para uso. Para testar os métodos de API Web que exigem o corpo da solicitação HTTP, é preciso definir um editor de texto padrão. A ferramenta HttpRepl inicia o editor de texto configurado somente para escrever o corpo da solicitação. Execute o seguinte comando para definir o editor de texto preferido como padrão:

pref set editor.command.default "<EXECUTABLE>"

No comando anterior, <EXECUTABLE> é o caminho completo para o arquivo executável do editor de texto. Por exemplo, execute o seguinte comando para definir o Visual Studio Code como o editor de texto padrão:

pref set editor.command.default "/usr/bin/code"

Para iniciar o editor de texto padrão com argumentos específicos da CLI, defina a chave editor.command.default.arguments. Por exemplo, imagine que o Visual Studio Code é o editor de texto padrão e que você quer que o HttpRepl sempre o abra em uma nova sessão com as extensões desabilitadas. Execute o comando a seguir:

pref set editor.command.default.arguments "--disable-extensions --new-window"

Dica

Se o editor padrão for o Visual Studio Code, você geralmente desejará passar o argumento -w ou --wait para forçar o Visual Studio Code esperar que você feche o arquivo antes de retornar.

Definir os caminhos de pesquisa de descrição do OpenAPI

Por padrão, HttpRepl tem um conjunto de caminhos relativos que usa para localizar a descrição do OpenAPI ao executar o comando connect sem a opção --openapi. Esses caminhos relativos são combinados com os caminhos raiz e base especificados no comando connect. Os caminhos relativos padrão são:

  • swagger.json
  • swagger/v1/swagger.json
  • /swagger.json
  • /swagger/v1/swagger.json
  • openapi.json
  • /openapi.json

Para usar um conjunto diferente de caminhos de pesquisa em seu ambiente, defina a preferência swagger.searchPaths. O valor precisa ser uma lista delimitada por pipes de caminhos relativos. Por exemplo:

pref set swagger.searchPaths "swagger/v2/swagger.json|swagger/v3/swagger.json"

Em vez de substituir completamente a lista padrão, a lista também pode ser modificada adicionando ou removendo caminhos.

Para adicionar um ou mais caminhos de pesquisa à lista padrão, defina a preferência swagger.addToSearchPaths. O valor precisa ser uma lista delimitada por pipes de caminhos relativos. Por exemplo:

pref set swagger.addToSearchPaths "openapi/v2/openapi.json|openapi/v3/openapi.json"

Para remover um ou mais caminhos de pesquisa à lista padrão, defina a preferência swagger.addToSearchPaths. O valor precisa ser uma lista delimitada por pipes de caminhos relativos. Por exemplo:

pref set swagger.removeFromSearchPaths "swagger.json|/swagger.json"

Testar solicitações HTTP GET

Sinopse

get <PARAMETER> [-F|--no-formatting] [-h|--header] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

As opções a seguir estão disponíveis para o comando get:

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

Exemplo

Para emitir uma solicitação HTTP GET:

  1. Execute o comando get em um ponto de extremidade compatível:

    https://localhost:5001/people> get
    

    O comando anterior exibirá o seguinte formato de saída:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Fri, 21 Jun 2019 03:38:45 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    [
      {
        "id": 1,
        "name": "Scott Hunter"
      },
      {
        "id": 2,
        "name": "Scott Hanselman"
      },
      {
        "id": 3,
        "name": "Scott Guthrie"
      }
    ]
    
    
    https://localhost:5001/people>
    
  2. Recupere um registro específico passando um parâmetro para o comando get:

    https://localhost:5001/people> get 2
    

    O comando anterior exibirá o seguinte formato de saída:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Fri, 21 Jun 2019 06:17:57 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    [
      {
        "id": 2,
        "name": "Scott Hanselman"
      }
    ]
    
    
    https://localhost:5001/people>
    

Testar solicitações HTTP POST

Sinopse

post <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

  • -c|--content

    Fornece um corpo de solicitação HTTP embutido. Por exemplo, -c "{\"id\":2,\"name\":\"Cherry\"}".

  • -f|--file

    Fornece um caminho para um arquivo que contém o corpo da solicitação HTTP. Por exemplo, -f "C:\request.json".

  • --no-body

    Indica que nenhum corpo de solicitação HTTP é necessário.

Exemplo

Para emitir uma solicitação HTTP POST:

  1. Execute o comando post em um ponto de extremidade compatível:

    https://localhost:5001/people> post -h Content-Type=application/json
    

    No comando anterior, o cabeçalho da solicitação HTTP Content-Type está configurado para indicar um tipo de mídia de corpo da solicitação do JSON. O editor de texto padrão abrirá um arquivo .tmp com um modelo JSON que representa o corpo da solicitação HTTP. Por exemplo:

    {
      "id": 0,
      "name": ""
    }
    

    Dica

    Para definir o editor de texto padrão, confira a seção Definir o editor de texto padrão.

  2. Modifique o modelo JSON para satisfazer os requisitos de validação de modelo:

    {
      "id": 0,
      "name": "Scott Addie"
    }
    
  3. Salve o arquivo .tmp e feche o editor de texto. A seguinte saída será exibida no shell de comando:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    Date: Thu, 27 Jun 2019 21:24:18 GMT
    Location: https://localhost:5001/people/4
    Server: Kestrel
    Transfer-Encoding: chunked
    
    {
      "id": 4,
      "name": "Scott Addie"
    }
    
    
    https://localhost:5001/people>
    

Testar solicitações HTTP PUT

Sinopse

put <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

  • -c|--content

    Fornece um corpo de solicitação HTTP embutido. Por exemplo, -c "{\"id\":2,\"name\":\"Cherry\"}".

  • -f|--file

    Fornece um caminho para um arquivo que contém o corpo da solicitação HTTP. Por exemplo, -f "C:\request.json".

  • --no-body

    Indica que nenhum corpo de solicitação HTTP é necessário.

Exemplo

Para emitir uma solicitação HTTP PUT:

  1. Opcional: execute o comando get para exibir os dados antes de modificá-los:

    https://localhost:5001/fruits> get
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Sat, 22 Jun 2019 00:07:32 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    [
      {
        "id": 1,
        "data": "Apple"
      },
      {
        "id": 2,
        "data": "Orange"
      },
      {
        "id": 3,
        "data": "Strawberry"
      }
    ]
    
  2. Execute o comando put em um ponto de extremidade compatível:

    https://localhost:5001/fruits> put 2 -h Content-Type=application/json
    

    No comando anterior, o cabeçalho da solicitação HTTP Content-Type está configurado para indicar um tipo de mídia de corpo da solicitação do JSON. O editor de texto padrão abrirá um arquivo .tmp com um modelo JSON que representa o corpo da solicitação HTTP. Por exemplo:

    {
      "id": 0,
      "name": ""
    }
    

    Dica

    Para definir o editor de texto padrão, confira a seção Definir o editor de texto padrão.

  3. Modifique o modelo JSON para satisfazer os requisitos de validação de modelo:

    {
      "id": 2,
      "name": "Cherry"
    }
    
  4. Salve o arquivo .tmp e feche o editor de texto. A seguinte saída será exibida no shell de comando:

    [main 2019-06-28T17:27:01.805Z] update#setState idle
    HTTP/1.1 204 No Content
    Date: Fri, 28 Jun 2019 17:28:21 GMT
    Server: Kestrel
    
  5. Opcional: emita um comando get para ver as modificações. Por exemplo, se você digitou "Cherry" no editor de texto, um get retornará a seguinte saída:

    https://localhost:5001/fruits> get
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Sat, 22 Jun 2019 00:08:20 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    [
      {
        "id": 1,
        "data": "Apple"
      },
      {
        "id": 2,
        "data": "Cherry"
      },
      {
        "id": 3,
        "data": "Strawberry"
      }
    ]
    
    
    https://localhost:5001/fruits>
    

Testar solicitações HTTP DELETE

Sinopse

delete <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

Exemplo

Para emitir uma solicitação HTTP DELETE:

  1. Opcional: execute o comando get para exibir os dados antes de modificá-los:

    https://localhost:5001/fruits> get
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Sat, 22 Jun 2019 00:07:32 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    [
      {
        "id": 1,
        "data": "Apple"
      },
      {
        "id": 2,
        "data": "Orange"
      },
      {
        "id": 3,
        "data": "Strawberry"
      }
    ]
    
  2. Execute o comando delete em um ponto de extremidade compatível:

    https://localhost:5001/fruits> delete 2
    

    O comando anterior exibirá o seguinte formato de saída:

    HTTP/1.1 204 No Content
    Date: Fri, 28 Jun 2019 17:36:42 GMT
    Server: Kestrel
    
  3. Opcional: emita um comando get para ver as modificações. Neste exemplo, um get retorna a seguinte saída:

    https://localhost:5001/fruits> get
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Sat, 22 Jun 2019 00:16:30 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    [
      {
        "id": 1,
        "data": "Apple"
      },
      {
        "id": 3,
        "data": "Strawberry"
      }
    ]
    
    
    https://localhost:5001/fruits>
    

Testar solicitações HTTP PATCH

Sinopse

patch <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

  • -c|--content

    Fornece um corpo de solicitação HTTP embutido. Por exemplo, -c "{\"id\":2,\"name\":\"Cherry\"}".

  • -f|--file

    Fornece um caminho para um arquivo que contém o corpo da solicitação HTTP. Por exemplo, -f "C:\request.json".

  • --no-body

    Indica que nenhum corpo de solicitação HTTP é necessário.

Testar solicitações HTTP HEAD

Sinopse

head <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

Testar solicitações HTTP OPTIONS

Sinopse

options <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--streaming]

Argumentos

PARAMETER

O parâmetro de rota, se houver, esperado pelo método de ação do controlador associado.

Opções

  • -F|--no-formatting

    Um sinalizador cuja presença suprime a formatação da resposta HTTP.

  • -h|--header

    Define um cabeçalho para a solicitação HTTP. Os dois formatos de valor a seguir são compatíveis:

    • {header}={value}
    • {header}:{value}
  • --response:body

    Especifica um arquivo em que o corpo da resposta HTTP deve ser gravado. Por exemplo, --response:body "C:\response.json". Se ainda não existir, o arquivo será criado.

  • --response:headers

    Especifica um arquivo em que os cabeçalhos da resposta HTTP devem ser gravados. Por exemplo, --response:headers "C:\response.txt". Se ainda não existir, o arquivo será criado.

  • -s|--streaming

    Um sinalizador cuja presença habilita o streaming da resposta HTTP.

Configurar cabeçalhos de solicitações HTTP

Para configurar um cabeçalho de solicitação HTTP, use uma das seguintes abordagens:

  • Configure embutido com a solicitação HTTP. Por exemplo:

    https://localhost:5001/people> post -h Content-Type=application/json
    

    Com a abordagem anterior, cada cabeçalho de solicitação HTTP diferente exige sua própria opção -h.

  • Configure antes de enviar a solicitação HTTP. Por exemplo:

    https://localhost:5001/people> set header Content-Type application/json
    

    Ao configurar o cabeçalho antes de enviar a solicitação, ele permanecerá configurado durante toda a sessão do shell de comando. Para limpar o cabeçalho, forneça um valor vazio. Por exemplo:

    https://localhost:5001/people> set header Content-Type
    

Testar pontos de extremidade protegidos

O HttpRepl dá suporte ao teste de pontos de extremidade protegidos das seguintes maneiras:

  • Por meio das credenciais padrão do usuário conectado.
  • Por meio do uso de cabeçalhos de solicitação HTTP.

Credenciais padrão

Considere uma API Web que você está testando que é hospedada no IIS e protegida com a autenticação do Windows. Você quer que as credenciais do usuário que executa a ferramenta fluam para os pontos de extremidade HTTP que estão sendo testados. Para passar as credenciais padrão do usuário conectado:

  1. Defina a preferência httpClient.useDefaultCredentials como true:

    pref set httpClient.useDefaultCredentials true
    
  2. Saia e reinicie a ferramenta antes de enviar outra solicitação para a API Web.

Credenciais de proxy padrão

Considere um cenário no qual a API Web que você está testando está por trás de um proxy protegido com autenticação do Windows. Você quer que as credenciais do usuário que executa a ferramenta fluam para o proxy. Para passar as credenciais padrão do usuário conectado:

  1. Defina a preferência httpClient.proxy.useDefaultCredentials como true:

    pref set httpClient.proxy.useDefaultCredentials true
    
  2. Saia e reinicie a ferramenta antes de enviar outra solicitação para a API Web.

Cabeçalhos de solicitação HTTP

Exemplos de esquemas de autenticação e autorização com suporte incluem:

  • basic authentication
  • Tokens de portador JWT
  • autenticação de código hash

Por exemplo, você pode enviar um token de portador para um ponto de extremidade com o seguinte comando:

set header Authorization "bearer <TOKEN VALUE>"

Para acessar um ponto de extremidade hospedado no Azure ou usar a API REST do Azure, você precisa de um token de portador. Use as etapas a seguir para obter um token de portador para sua assinatura do Azure por meio da CLI do Azure. HttpRepl define o token de portador em um cabeçalho de solicitação HTTP. Uma lista de Aplicativos Web do Serviço de Aplicativo do Azure é recuperada.

  1. Entrar no Azure:

    az login
    
  2. Obtenha sua ID de assinatura com o seguinte comando:

    az account show --query id
    
  3. Copie a ID de assinatura e execute o seguinte comando:

    az account set --subscription "<SUBSCRIPTION ID>"
    
  4. Obtenha o token de portador com o seguinte comando:

    az account get-access-token --query accessToken
    
  5. Conecte-se à API REST do Azure por meio do HttpRepl:

    httprepl https://management.azure.com
    
  6. Defina o cabeçalho da solicitação HTTP Authorization:

    https://management.azure.com/> set header Authorization "bearer <ACCESS TOKEN>"
    
  7. Navegue até a assinatura:

    https://management.azure.com/> cd subscriptions/<SUBSCRIPTION ID>
    
  8. Obtenha uma lista de Aplicativos Web do Serviço de Aplicativo do Azure de sua assinatura:

    https://management.azure.com/subscriptions/{SUBSCRIPTION ID}> get providers/Microsoft.Web/sites?api-version=2016-08-01
    

    A seguinte resposta é exibida:

    HTTP/1.1 200 OK
    Cache-Control: no-cache
    Content-Length: 35948
    Content-Type: application/json; charset=utf-8
    Date: Thu, 19 Sep 2019 23:04:03 GMT
    Expires: -1
    Pragma: no-cache
    Strict-Transport-Security: max-age=31536000; includeSubDomains
    X-Content-Type-Options: nosniff
    x-ms-correlation-request-id: <em>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</em>
    x-ms-original-request-ids: <em>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx;xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</em>
    x-ms-ratelimit-remaining-subscription-reads: 11999
    x-ms-request-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    x-ms-routing-request-id: WESTUS:xxxxxxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
    {
      "value": [
        <AZURE RESOURCES LIST>
      ]
    }
    

Alternar exibição da solicitação HTTP

Por padrão, a exibição da solicitação HTTP que está sendo enviada é suprimida. É possível alterar a configuração correspondente durante a sessão do shell de comando.

Habilitar a exibição da solicitação

Exiba a solicitação HTTP que está sendo enviada executando o comando echo on. Por exemplo:

https://localhost:5001/people> echo on
Request echoing is on

As solicitações HTTP subsequentes na sessão atual exibem os cabeçalhos de solicitação. Por exemplo:

https://localhost:5001/people> post

[main 2019-06-28T18:50:11.930Z] update#setState idle
Request to https://localhost:5001...

POST /people HTTP/1.1
Content-Length: 41
Content-Type: application/json
User-Agent: HTTP-REPL

{
  "id": 0,
  "name": "Scott Addie"
}

Response from https://localhost:5001...

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Jun 2019 18:50:21 GMT
Location: https://localhost:5001/people/4
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 4,
  "name": "Scott Addie"
}


https://localhost:5001/people>

Desabilitar a exibição da solicitação

Suprima a exibição da solicitação HTTP que está sendo enviada executando o comando echo off. Por exemplo:

https://localhost:5001/people> echo off
Request echoing is off

Executar um script

Se você executar com frequência o mesmo conjunto de comandos HttpRepl, considere armazená-los em um arquivo de texto. Os comandos no arquivo assumem a mesma forma que aqueles executados manualmente na linha de comando. Os comandos podem ser executados em um modo em lote usando o comando run. Por exemplo:

  1. Crie um arquivo de texto com um conjunto de comandos delimitados por nova linha. Para ilustrar, considere um arquivo people-script.txt com os seguintes comandos:

    set base https://localhost:5001
    ls
    cd People
    ls
    get 1
    
  2. Execute o comando run, passando o caminho do arquivo de texto. Por exemplo:

    https://localhost:5001/> run C:\http-repl-scripts\people-script.txt
    

    O seguinte resultado é exibido:

    https://localhost:5001/> set base https://localhost:5001
    Using OpenAPI description at https://localhost:5001/swagger/v1/swagger.json
    
    https://localhost:5001/> ls
    .        []
    Fruits   [get|post]
    People   [get|post]
    
    https://localhost:5001/> cd People
    /People    [get|post]
    
    https://localhost:5001/People> ls
    .      [get|post]
    ..     []
    {id}   [get|put|delete]
    
    https://localhost:5001/People> get 1
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Fri, 12 Jul 2019 19:20:10 GMT
    Server: Kestrel
    Transfer-Encoding: chunked
    
    {
      "id": 1,
      "name": "Scott Hunter"
    }
    
    
    https://localhost:5001/People>
    

Limpar a saída

Para remover toda a saída gravada no shell de comando pela ferramenta HttpRepl, execute os comandos clear ou cls. Para ilustrar, imagine que o shell de comando contém a seguinte saída:

httprepl https://localhost:5001
(Disconnected)> set base "https://localhost:5001"
Using OpenAPI description at https://localhost:5001/swagger/v1/swagger.json

https://localhost:5001/> ls
.        []
Fruits   [get|post]
People   [get|post]

https://localhost:5001/>

Execute o comando a seguir para limpar a saída:

https://localhost:5001/> clear

Após a execução o comando anterior, o shell de comando conterá somente a seguinte saída:

https://localhost:5001/>

Recursos adicionais