Como emitir solicitações HTTP(S)

ID de região

O REGION_ID é um código abreviado que o Google atribui com base na região que você selecionou ao criar o aplicativo. O código não corresponde a um país ou estado, ainda que alguns IDs de região sejam semelhantes aos códigos de país e estado geralmente usados. Para apps criados após fevereiro de 2020, o REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criados antes dessa data, o ID da região é opcional no URL.

Saiba mais sobre IDs de região.

OK

Esta página descreve como emitir solicitações HTTP(S) do seu aplicativo App Engine.

Por padrão, os aplicativos em execução no ambiente de execução do Java 8 usam classes Java padrão para solicitações HTTP(S), como java.net.HttpURLConnection. Você envia solicitações exatamente como faria para qualquer outro aplicativo Java. Para usar o comportamento padrão, você precisa ativar o faturamento para seu aplicativo ou receberá as seguintes exceções:

• java.net.UnknownHostException
• java.net.SocketTimeoutException
• java.io.IOException

Como usar classes de rede de ambiente de execução padrão

Se você usar as classes de rede Java padrão, seu aplicativo terá acesso aos seguintes recursos:

• remoção do limite de 32 MB para os dados da solicitação.
• suporte para HTTP 2.0.
• É compatível com todas as APIs do Google Cloud, acessadas por meio da Biblioteca de cliente do Google Cloud para Java.

Como usar a busca de URL

Aviso: não use a busca de URL se você tiver configurado o acesso VPC sem servidor ou usado bibliotecas de cliente do Cloud para Java. A busca de URL processará todas as solicitações de saída e causará falha nas solicitações enviadas à sua rede VPC ou às bibliotecas de cliente. Se algum destes for seu caso, verifique se o campo url-stream-handler na sua configuração não está definido como urlfetch. Aplicativos que usam bibliotecas de cliente do Cloud para Java e tentam usar a busca de URL pelo wrapper URLConnection não são compatíveis.

Se você precisar usar o URL Fetch em um aplicativo Java 8, adicione a seguinte linha ao arquivo appengine-web.xml:

 <url-stream-handler>urlfetch</url-stream-handler>

Exemplo:

<xml version="1.0" encoding="utf-8">
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>

Observação: o servidor de metadados só pode ser acessado com soquetes Java nativos e o gerenciador de stream nativo e não é compatível com o serviço urlfetch.

Como emitir solicitações HTTP

Emita uma solicitação HTTP de saída usando java.net.URLConnection.

O snippet a seguir demonstra como executar uma solicitação básica HTTP GET. O aplicativo cria um novo objeto URL e chama o método openStream() do objeto para recuperar o conteúdo nesse URL:

URL url = new URL("http://api.icndb.com/jokes/random");
BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream()));
StringBuffer json = new StringBuffer();
String line;

while ((line = reader.readLine()) != null) {
  json.append(line);
}
reader.close();

Para solicitações mais avançadas, use java.net.HttpURLConnection da seguinte maneira:

1. Crie um novo objeto URL.
2. Crie um novo objeto URLConnection chamando o método openConnection() do objeto URL.
3. Crie um novo objeto HttpURLConnection transmitindo seu objeto URLConnection para o tipo de objeto HttpURLConnection.
4. Defina o método de solicitação do objeto HttpURLConnection.
5. Crie um stream de saída para a solicitação.
6. Grave o payload da solicitação no stream.
7. Feche o stream.

O snippet a seguir demonstra como usar HttpURLConnection para executar uma solicitação mais avançada, enviando dados de um formulário da Web por meio de uma solicitação PUT:

URL url = new URL("http://jsonplaceholder.typicode.com/posts/" + id);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
// Enable output for the connection.
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
conn.setRequestProperty("Accept", "application/json");
// Set HTTP request method.
conn.setRequestMethod("PUT");

// Create JSON request.
JSONObject jsonObj =
    new JSONObject().put("userId", 1).put("id", id).put("title", text).put("body", text);

OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream());
writer.write(jsonObj.toString());
writer.close();

int respCode = conn.getResponseCode(); // New items get NOT_FOUND on PUT
if (respCode == HttpURLConnection.HTTP_OK || respCode == HttpURLConnection.HTTP_NOT_FOUND) {
  req.setAttribute("error", "");
  StringBuilder response = new StringBuilder();
  String line;

  // Read input data stream.
  BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));
  while ((line = reader.readLine()) != null) {
    response.append(line);
  }
  reader.close();
  req.setAttribute("response", response.toString());
} else {
  req.setAttribute("error", conn.getResponseCode() + " " + conn.getResponseMessage());
}

Como definir um tempo limite de solicitação

Se você estiver usando a busca de URL, poderá ajustar o prazo padrão para solicitações usando a configuração appengine.api.urlfetch.defaultDeadline no arquivo appengine-web.xml.

Como definir cabeçalhos

Se você estiver usando a busca de URL, poderá definir um cabeçalho HTTP na solicitação de saída chamando o método setRequestProperty() do objeto HttpURLConnection. O snippet a seguir define o cabeçalho X-MyApp-Version como 2.7.3:

conn.setRequestProperty("X-MyApp-Version", "2.7.3");

Como desativar redirecionamentos

Importante: para melhorar a segurança do app, é recomendável desativar os redirecionamentos.

Por padrão, HttpURLConnection segue redirecionamentos HTTP.

Se você estiver usando a busca de URL, o serviço subjacente de busca de URL seguirá até cinco redirecionamentos por padrão. Esses redirecionamentos podem encaminhar informações confidenciais, como cabeçalhos de autorização, para o destino redirecionado. Se o aplicativo não exigir redirecionamentos HTTP, é recomendável que você os desative.

Para desativar esse comportamento, transmita o valor false para o método setInstanceFollowRedirects() do objeto HttpURLConnection:

conn.setInstanceFollowRedirects(false);

Se o aplicativo usar o pacote urlfetch subjacente diretamente em vez de java.net, ele precisará especificar doNotFollowRedirects.

Como emitir solicitações HTTPS

Se você estiver usando a busca de URL, emita uma solicitação HTTPS usando a classe FetchOptions no pacote urlfetch e chame validateCertificate().

Como emitir uma solicitação assíncrona

As solicitações HTTP(S) são síncronas por padrão. Para emitir uma solicitação assíncrona, seu aplicativo precisa usar o método fetchAsync() de URLFetchService. Esse método retorna um java.util.concurrent.Future<HTTPResponse>.

Como emitir solicitações para outro aplicativo do App Engine

Ao emitir uma solicitação para outro aplicativo do App Engine, ele precisa declarar a identidade dele adicionando o cabeçalho X-Appengine-Inbound-Appid à solicitação. Se você instruir o serviço de busca de URL a não seguir redirecionamentos, o App Engine adicionará esse cabeçalho às solicitações automaticamente.

Consulte Como desativar redirecionamentos para orientação sobre como desativar redirecionamentos.

Observação: se você estiver fazendo solicitações para outro aplicativo do App Engine, use o nome de domínio REGION_ID.r.appspot.com dele em vez de um domínio personalizado para o aplicativo.

A seguir

Para saber mais sobre o serviço de busca de URL, como os cabeçalhos que são enviados em uma solicitação de busca de URL, consulte Solicitações de saída.