Emitir pedidos HTTP(S)

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

OK

Esta página descreve como emitir pedidos HTTP(S) a partir da sua app do App Engine.

Por predefinição, as aplicações executadas no tempo de execução do Java 8 usam classes Java padrão para pedidos HTTP(S), como java.net.HttpURLConnection. Envia pedidos como faria para qualquer outra aplicação Java. Para usar o comportamento predefinido, tem de ativar a faturação para a sua aplicação. Caso contrário, recebe as seguintes exceções:

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

Usar classes de rede de tempo de execução padrão

Se usar as classes de rede Java padrão, a sua app tem acesso às seguintes funcionalidades:

• O limite de 32 MB nos dados de pedidos é removido.
• Suporte para HTTP 2.0.
• Suporta todas as APIs baseadas no Google Cloud acessíveis a partir da biblioteca cliente do Google Cloud para Java.

Usar a obtenção de URLs

Aviso: não use a obtenção de URLs se tiver configurado o acesso a VPC sem servidor ou usar as bibliotecas cliente da Google Cloud para Java. A obtenção de URLs processa todos os pedidos de saída e faz com que os pedidos que envia para a sua rede VPC ou as bibliotecas de cliente falhem. Se algum destes cenários se aplicar a si, certifique-se de que o campo url-stream-handler na sua configuração não está definido como urlfetch. As apps que usam as bibliotecas cliente da Google Cloud para Java e tentam usar a obtenção de URLs através do wrapper URLConnection não são suportadas.

Se tiver de usar a API URL Fetch numa app Java 8, adicione a seguinte linha ao ficheiro appengine-web.xml:

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

Por 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>

Nota: só é possível aceder ao servidor de metadados através de sockets Java nativos e do controlador de streams nativo, e não suporta o serviço urlfetch.

Emitir um pedido HTTP

Envia um pedido HTTP de saída através de java.net.URLConnection.

O fragmento seguinte demonstra como fazer um pedido HTTP GET básico. A aplicação cria um novo objeto URL e, em seguida, chama o método openStream() do objeto para obter 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 pedidos mais avançados, use java.net.HttpURLConnection da seguinte forma:

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 convertendo o seu objeto URLConnection no tipo de objeto HttpURLConnection.
4. Defina o método de pedido do objeto HttpURLConnection.
5. Crie uma stream de saída para o pedido.
6. Escreva o payload do pedido na stream.
7. Feche a stream.

O fragmento seguinte demonstra como usar HttpURLConnection para fazer um pedido mais avançado, enviando dados de um formulário Web através de um pedido 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());
}

Defina um limite de tempo do pedido

Se estiver a usar a obtenção de URLs, pode ajustar o prazo predefinido para pedidos usando a definição appengine.api.urlfetch.defaultDeadline no ficheiro appengine-web.xml.

Definir cabeçalhos

Se estiver a usar a obtenção de URLs, pode definir um cabeçalho HTTP no pedido de saída chamando o método setRequestProperty() do objeto HttpURLConnection. O fragmento seguinte define o cabeçalho X-MyApp-Version como 2.7.3:

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

Desative os redirecionamentos

Importante: para melhorar a segurança da sua app, recomendamos que desative os redirecionamentos.

Por predefinição, o HttpURLConnection segue os redirecionamentos HTTP.

Se estiver a usar a obtenção de URL, o serviço de obtenção de URL subjacente segue até cinco redirecionamentos por predefinição. Estes redirecionamentos podem encaminhar informações confidenciais, como cabeçalhos de autorização, para o destino redirecionado. Se a sua app não requerer redirecionamentos HTTP, recomendamos que os desative.

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

conn.setInstanceFollowRedirects(false);

Se a sua app usar o pacote urlfetch subjacente diretamente em vez de java.net, tem de especificar doNotFollowRedirects.

Emitir um pedido HTTPS

Por predefinição, o serviço URL Fetch subjacente valida o certificado do anfitrião que contacta e rejeita pedidos se o certificado não corresponder. Não precisa de proteger explicitamente o seu pedido.

Desative a validação de certificados de anfitrião

Para desativar a validação automática de certificados de anfitriões na obtenção de URLs, envie um pedido HTTPS através da classe FetchOptions no pacote urlfetch e chame doNotValidateCertificate().

Emita um pedido assíncrono

Os pedidos HTTP(S) são síncronos por predefinição. Para emitir um pedido assíncrono, a sua aplicação tem de usar o método URLFetchServicefetchAsync(). Este método devolve um java.util.concurrent.Future<HTTPResponse>.

Emitir um pedido para outra app do App Engine

Quando emite um pedido para outra app do App Engine, a sua app do App Engine tem de afirmar a sua identidade adicionando o cabeçalho X-Appengine-Inbound-Appid ao pedido. Se instruir o serviço URL Fetch para não seguir redirecionamentos, o App Engine adiciona este cabeçalho aos pedidos automaticamente.

Consulte o artigo Desativar redirecionamentos para obter orientações sobre como desativar redirecionamentos.

Nota: se estiver a fazer pedidos a outra aplicação do App Engine, use o respetivo nome de domínio REGION_ID.r.appspot.com em vez de um domínio personalizado para a sua app.

O que se segue?

Saiba mais sobre o serviço de obtenção de URL, como os cabeçalhos que são enviados num pedido de obtenção de URL em Pedidos de saída.