请求级别客户端 API

Request-Level Client-Side API

The request-level API is the recommended and most convenient way of using Akka HTTP’s client-side functionality. It internally builds upon the Host-Level Client-Side API to provide you with a simple and easy-to-use way of retrieving HTTP responses from remote servers. Depending on your preference you can pick the flow-based or the future-based variant.

请求级别 API 是使用 Akka HTTP 的客户端功能的推荐和最方便的方法。它内部建立在 主机级别客户端 API 之上， 为你提供从远程服务器检索 HTTP 响应的简单易用的方式。

Future-Based Variant

基于 Future 的变体

Most often, your HTTP client needs are very basic. You simply need the HTTP response for a certain request and don’t want to bother with setting up a full-blown streaming infrastructure.

通常，你的 HTTP 客户端需要是很基础的。你只需要某个请求进行 HTTP 响应，不想费心设置一个完善的流处理基础设施。

For these cases Akka HTTP offers the Http().singleRequest(...)Http.get(system).singleRequest(...) method, which simply turns an HttpRequestHttpRequest instance into Future[HttpResponse]CompletionStage<HttpResponse>. Internally the request is dispatched across the (cached) host connection pool for the request’s effective URI.

对于这些情况，Akka HTTP 提供了 Http().singleRequest(...)Http.get(system).singleRequest(...) 方法， 该方法简单地将 HttpRequestHttpRequest 实例转换为 Future[HttpResponse]CompletionStage<HttpResponse> 。 在内部，以请求的有效 URI 将请求分配到跨（缓存的）主机连接池。

Just like in the case of the super-pool flow described above the request must have either an absolute URI or a valid Host header, otherwise the returned future will be completed with an error.

就像上面超级连接池的情况描述的，请求必须包含包含 URI 路径或者有一个有效的 Host 头域，否则返回的 Future 将以一个错误完成。

Example

示例

Scala

import akka.actor.ActorSystem
import akka.http.scaladsl.Http
import akka.http.scaladsl.model._
import akka.stream.ActorMaterializer

import scala.concurrent.Future
import scala.util.{ Failure, Success }

object Client {
  def main(args: Array[String]): Unit = {
    implicit val system = ActorSystem()
    implicit val materializer = ActorMaterializer()
    // needed for the future flatMap/onComplete in the end
    implicit val executionContext = system.dispatcher

    val responseFuture: Future[HttpResponse] = Http().singleRequest(HttpRequest(uri = "http://akka.io"))

    responseFuture
      .onComplete {
        case Success(res) => println(res)
        case Failure(_)   => sys.error("something wrong")
      }
  }
}

Java

final ActorSystem system = ActorSystem.create();

final CompletionStage<HttpResponse> responseFuture =
  Http.get(system)
      .singleRequest(HttpRequest.create("http://akka.io"));

Using the Future-Based API in Actors

在 Actor 里使用基于 Future 的 API

When using the FutureCompletionStage based API from inside an ActorActor, all the usual caveats apply to how one should deal with the futures completion. For example you should not access the actor’s state from within the FutureCompletionStage’s callbacks (such as map, onComplete, …) and instead you should use the pipeTopipe pattern to pipe the result back to the actor as a message:

当从 ActorActor 内部使用基于 FutureCompletionStage 的 API时，所有常见的警告都适用于如何处理 Future 完成。 如使：在 FutureCompletionStage 的回调（如：map、onComplete、……）里不应该访问 Actor 的状态，你应该使用 pipeTopipe 模式将（Future 的）结果通过管道作为消息发回 actor 。

Scala

import akka.actor.{ Actor, ActorLogging }
import akka.http.scaladsl.Http
import akka.http.scaladsl.model._
import akka.stream.{ ActorMaterializer, ActorMaterializerSettings }
import akka.util.ByteString

class Myself extends Actor
  with ActorLogging {

  import akka.pattern.pipe
  import context.dispatcher

  final implicit val materializer: ActorMaterializer = ActorMaterializer(ActorMaterializerSettings(context.system))

  val http = Http(context.system)

  override def preStart() = {
    http.singleRequest(HttpRequest(uri = "http://akka.io"))
      .pipeTo(self)
  }

  def receive = {
    case HttpResponse(StatusCodes.OK, headers, entity, _) =>
      entity.dataBytes.runFold(ByteString(""))(_ ++ _).foreach { body =>
        log.info("Got response, body: " + body.utf8String)
      }
    case resp @ HttpResponse(code, _, _, _) =>
      log.info("Request failed, response code: " + code)
      resp.discardEntityBytes()
  }

}

Java

import akka.actor.AbstractActor;
import akka.http.javadsl.Http;
import akka.http.javadsl.model.HttpRequest;
import akka.http.javadsl.model.HttpResponse;
import akka.stream.ActorMaterializer;
import akka.stream.Materializer;
import scala.concurrent.ExecutionContextExecutor;

import java.util.concurrent.CompletionStage;

import static akka.pattern.PatternsCS.pipe;

class SingleRequestInActorExample extends AbstractActor {
  final Http http = Http.get(context().system());
  final ExecutionContextExecutor dispatcher = context().dispatcher();
  final Materializer materializer = ActorMaterializer.create(context());

  @Override
  public Receive createReceive() {
    return receiveBuilder()
      .match(String.class, url -> pipe(fetch(url), dispatcher).to(self()))
      .build();
  }

  CompletionStage<HttpResponse> fetch(String url) {
    return http.singleRequest(HttpRequest.create(url));
  }
}

Flow-Based Variant

基于 Flow 的变体

The flow-based variant of the request-level client-side API is presented by the Http().superPool(...)Http.get(system).superPool(...) method. It creates a new “super connection pool flow”, which routes incoming requests to a (cached) host connection pool depending on their respective effective URIs.

请求级别客户端 API 的基于 Flow 的变体由 Http().superPool(...)Http.get(system).superPool(...) 方法表示。 它创建一个新的“超级连接池 flow”，将传入请求路由到一个（缓存的）主机连接池，（路由算法）具体取决于它们各自的有效 URI。

The FlowFlow returned by Http().superPool(...)Http.get(system).superPool(...) is very similar to the one from the Host-Level Client-Side API, so the Using a Host Connection Pool section also applies here.

因为通过 Http().superPool(...)Http.get(system).superPool(...) 返回的 FlowFlow 非常类似 主机级别客户端 API 返回的 FlowFlow ，所以 使用一个主机连接池 部分描述的内容也适用与这里。

However, there is one notable difference between a “host connection pool client flow” for the host-level API and a “super-pool flow”: Since in the former case the flow has an implicit target host context the requests it takes don’t need to have absolute URIs or a valid Host header. The host connection pool will automatically add a Host header if required.

但是，主机级别 API 的“主机连接池客户端 flow”和“超级池”之间有一个值得注意的区别： 因为在前一种情况下，flow 具有一个请求的隐式目标主机上下文，所以 flow 接收的请求不需要有绝对 URI 或者有效的 Host 头域。 如果需要，主机连接池将自动添加一个 Host 头域。

For a super-pool flow this is not the case. All requests to a super-pool must either have an absolute URI or a valid Host header, because otherwise it’d be impossible to find out which target endpoint to direct the request to.

而对于”超级池 flow“，情况并非如此。到超级池的所有请求都必须具有绝对 URI 或有效 Host 头域之一， 否则超级池将无法找到请求该定向到哪个目标端点。

Collecting headers from a server response

从服务器响应收集头域

Sometimes we would like to get only headers of specific type which are sent from a server. In order to collect headers in a type safe way Akka HTTP API provides a type for each HTTP header. Here is an example for getting all cookies set by a server (Set-Cookie header):

有时我们只想获得从服务器发送的特定类型的头域。为了以类型安全的方式收集头域，Akka HTTP API 为每个 HTTP 头域提供了类型。 这里是一个通过服务器获得所有 cookie 设置的（Set-Cookie 头域）：

Scala

import akka.actor.ActorSystem
import akka.http.scaladsl.Http
import akka.http.scaladsl.model.headers.`Set-Cookie`
import akka.http.scaladsl.model._
import akka.stream.ActorMaterializer

import scala.concurrent.ExecutionContextExecutor
import scala.concurrent.Future

object Client {
  def main(args: Array[String]): Unit = {
    implicit val system: ActorSystem = ActorSystem()
    implicit val materializer: ActorMaterializer = ActorMaterializer()
    implicit val executionContext: ExecutionContextExecutor = system.dispatcher

    val responseFuture: Future[HttpResponse] = Http().singleRequest(HttpRequest(uri = "http://akka.io"))

    responseFuture.map {
      case response @ HttpResponse(StatusCodes.OK, _, _, _) =>
        val setCookies = response.headers[`Set-Cookie`]
        println(s"Cookies set by a server: $setCookies")
        response.discardEntityBytes()
      case _ => sys.error("something wrong")
    }
  }
}

Java

final HttpResponse response = responseFromSomewhere();

final Iterable<SetCookie> setCookies = response.getHeaders(SetCookie.class);

System.out.println("Cookies set by a server: " + setCookies);
response.discardEntityBytes(materializer);

（译注：不要忘记调用 response.discardEntityBytes()）