Guide to ScribeJava – ScribeJava指南

最后修改: 2018年 9月 27日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

In this tutorial, we’re going to look at the ScribeJava library.

在本教程中，我们要看一下ScribeJava库。

ScribeJava is a simple OAuth client for Java which helps manage the OAuth flow.

ScribeJava是一个用于Java的简单OAuth客户端，它有助于管理OAuth流程。

The main feature of the library is that it supports all major 1.0 and 2.0 OAuth APIs out-of-the-box. Moreover, if we’ll have to work with an API that’s not supported, the library provides a couple of classes for implements our OAuth’s APIs.

该库的主要特点是，它支持所有主要的1.0和2.0 OAuth APIs，即开即用。此外，如果我们不得不使用一个不被支持的API，该库提供了几个类来实现我们的OAuth的API。

Another important feature is that is possible to choose which client use. Indeed, ScribeJava supports several HTTP clients:

另一个重要的特点是，可以选择使用哪个客户端。事实上，ScribeJava支持几个HTTP客户端。

Furthermore, the library is thread-safe and Java7-compatible, so we can use it in legacy environments.

此外，该库是线程安全的，与Java7兼容，所以我们可以在传统环境中使用它。

2. Dependencies

2.依赖性

ScribeJava is organized into a core and APIs module, the latter includes a set of external API (Google, GitHub, Twitter, etc) and the core artifact:

ScribeJava被组织成一个核心和API模块，后者包括一组外部API（Google、GitHub、Twitter等）和核心神器。

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-apis</artifactId>
    <version>latest-version</version>
</dependency>

In case we need just core classes without any external API, we have to pull just the core module:

如果我们只需要核心类而不需要任何外部API，我们必须只拉动核心模块。

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-core</artifactId>
    <version>latest-version</version>
</dependency>

The latest versions can be found at Maven repository.

最新版本可以在Maven仓库找到。

3. OAuthService

3.OAuthService

The main part of the library is the abstract class OAuthService which contains all the parameters needed to correctly manage the OAuth’s ‘handshake’.

该库的主要部分是抽象类OAuthService，它包含正确管理OAuth的 “握手 “所需的所有参数。

Depending on the version of the protocol, we’ll use Oauth10Service or Oauth20Service concrete classes respectively for OAuth 1.0 and OAuth 2.0.

根据协议的版本，我们将使用Oauth10Service或Oauth20Service具体类分别用于OAuth 1.0和OAuth 2.0。

In order to build the OAuthService implementations, the library provides a ServiceBuilder:

为了构建OAuthService实现，该库提供了一个ServiceBuilder：。

OAuthService service = new ServiceBuilder("api_key")
  .apiSecret("api_secret")
  .scope("scope")
  .callback("callback")
  .build(GoogleApi20.instance());

We should set the api_key and the api_secret tokens provided by the authorization server.

我们应该设置授权服务器提供的api_key和api_secret令牌。

Also, we can set the scope of the request and the callback to which the authorization server should redirect the user at the end of the authorization flow.

此外，我们还可以设置请求的范围和授权服务器在授权流程结束时应重定向用户的回调。

Note that depending on the version of the protocol not all parameters are mandatory.

请注意，根据协议的版本，并非所有参数都是强制性的。

Finally, we have to build the OAuthService calling the build() method and passing it an instance of the APIs we want to use. We can find a full list of the APIs supported at ScribeJava GitHub.

最后，我们必须构建OAuthService，调用build()方法，并将我们要使用的API的实例传递给它。我们可以在 ScribeJava GitHub上找到支持的 API 的完整列表。

3.1. HTTP Client

3.1. HTTP客户端

Moreover, the library allows us to choose which HTTP Client to use:

此外，该库允许我们选择使用哪个HTTP客户端：。

ServiceBuilder builder = new ServiceBuilder("api_key")
  .httpClient(new OkHttpHttpClient());

After, of course, we have included the required dependencies, for the previous example:

当然，在这之前，我们已经包含了所需的依赖性，对于前面的例子。

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-httpclient-okhttp</artifactId>
    <version>latest-version</version>
</dependency>

The latest versions can be found at Maven repository.

最新版本可以在Maven仓库找到。

3.2. Debug Mode

3.2.Debug模式

In addition, there’s a debug mode we can use to help us troubleshooting:

此外，还有一个调试模式，我们可以用来帮助我们排除故障：。

ServiceBuilder builder = new ServiceBuilder("api_key")
  .debug();

We simply have to call debug() method. Debug will output to System.out some relevant information.

我们只需调用debug()方法。Debug将向System.out输出一些相关信息。

Also, if we want to use a different output, there’s another method that accepts an OutputStream to send the debugging information to:

另外，如果我们想使用不同的输出，还有一个方法接受一个OutputStream来发送调试信息。

FileOutputStream debugFile = new FileOutputStream("debug");

ServiceBuilder builder = new ServiceBuilder("api_key")
  .debug()
  .debugStream(debugFile);

4. OAuth 1.0 Flow

4.OAuth 1.0流程

Now let’s focus on how to handle an OAuth1 flow.

现在让我们集中讨论如何处理OAuth1流。

In this example, we’re going to get an access token with the Twitter APIs and we’ll use it to make a request.

在这个例子中，我们将通过Twitter APIs获得一个访问令牌，我们将使用它来进行请求。

First of all, we have to build the Oauth10Service, as we saw earlier, using builder:

首先，我们必须建立Oauth10Service，正如我们之前看到的，使用builder。

OAuth10aService service = new ServiceBuilder("api_key")
  .apiSecret("api_secret")
  .build(TwitterApi.instance());

Once we have the OAuth10Service, we can get a requestToken and use it to get the authorization URL:

一旦我们有了OAuth10Service，我们就可以得到一个requestToken并使用它来获得授权URL。

OAuth1RequestToken requestToken = service.getRequestToken();
String authUrl = service.getAuthorizationUrl(requestToken);

At this point, it’s necessary to redirect the user to authUrl and to get the oauthVerifier provided by the page.

此时，有必要将用户重定向到authUrl，并获得页面提供的oauthVerifier。

Hence, we use the oauthVerifier to get the accessToken:

因此，我们使用oauthVerifier来获得accessToken。

OAuth1AccessToken accessToken = service.getAccessToken(requestToken,oauthVerifier);

Finally, we can create a request using OAuthRequest object and add the token to it with signRequest() method:

最后，我们可以使用OAuthRequest对象创建一个请求，并通过signRequest()方法将令牌加入其中。

OAuthRequest request = new OAuthRequest(Verb.GET, 
    "https://api.twitter.com/1.1/account/verify_credentials.json");
service.signRequest(accessToken, request);

Response response = service.execute(request);

As a result of the execution of that request, we get a Response object.

作为执行该request的结果，我们得到一个Response对象。

5. OAuth 2.0 Flow

5.OAuth 2.0流程

The OAuth 2.0 flow is not much different from OAuth 1.0. In order to explain these variations, we’re going to get an access token with Google APIs.

OAuth 2.0的流程与OAuth 1.0没有太大区别。为了解释这些变化，我们要用Google APIs获得一个access token。

In the same way, we did in the OAuth 1.0 flow, we have to build the OAuthService and get the authUrl, but this time we’ll use an OAuth20Service instance:

与OAuth 1.0的流程相同，我们必须建立OAuthService并获得authUrl，但这次我们将使用一个OAuth20Service实例。

OAuth20Service service = new ServiceBuilder("api_key")
  .apiSecret("api_secret")
  .scope("https://www.googleapis.com/auth/userinfo.email")
  .callback("http://localhost:8080/auth")
  .build(GoogleApi20.instance());

String authUrl = service.getAuthorizationUrl();

Note that, in this case, we need to provide the scope of the request and the callback to which we’ll be contacted at the end of the authorization flow.

请注意，在这种情况下，我们需要提供请求的范围和在授权流程结束时与我们联系的回调。

Likewise, we have to redirect the user to authUrl and take the code parameter in the url of the callback:

同样地，我们必须将用户重定向到authUrl，并在回调的url中获取code参数。

OAuth2AccessToken accessToken = service.getAccessToken(code);

OAuthRequest request = new OAuthRequest(Verb.GET, "https://www.googleapis.com/oauth2/v1/userinfo?alt=json");
service.signRequest(accessToken, request);

Response response = service.execute(request);

In the end, in order to make the request, we get the accessToken with getAccessToken() method.

最后，为了进行request，我们用getAccessToken()方法获得accessToken。

6. Custom APIs

6.自定义API

We’ll probably have to work with an API that’s not supported by ScribeJava. Under those circumstances, the library allows us to implement our own APIs.

我们可能不得不使用ScribeJava不支持的API。在这些情况下，该库允许我们实现自己的 API。

The only thing we need to do is to provide an implementation of DefaultApi10 or DefaultApi20 class.

我们唯一需要做的是提供一个DefaultApi10或DefaultApi20类的实现。

Let’s imagine we have an OAuth 2.0 authorization server with password grant. In this case, we can implement the DefaultApi20 so that we can take an access token:

让我们想象一下，我们有一个带有密码授权的OAuth 2.0授权服务器。在这种情况下，我们可以实现DefaultApi20，这样我们就可以获得一个access token。

public class MyApi extends DefaultApi20 {

    public MyApi() {}

    private static class InstanceHolder {
        private static final MyApi INSTANCE = new MyApi();
    }

    public static MyApi instance() {
        return InstanceHolder.INSTANCE;
    }

    @Override
    public String getAccessTokenEndpoint() {
        return "http://localhost:8080/oauth/token";
    }

    @Override
    protected String getAuthorizationBaseUrl() {
        return null;
    }
}

Thus, we can get an access token in a similar fashion as we did before:

因此，我们可以像以前那样，以类似的方式获得访问令牌。

OAuth20Service service = new ServiceBuilder("baeldung_api_key")
  .apiSecret("baeldung_api_secret")
  .scope("read write")
  .build(MyApi.instance());

OAuth2AccessToken token = service.getAccessTokenPasswordGrant(username, password);

OAuthRequest request = new OAuthRequest(Verb.GET, "http://localhost:8080/me");
service.signRequest(token, request);
Response response = service.execute(request);

7. Conclusion

7.结论

In this article, we took a look at the most useful classes that ScribeJava provides off the shelf.

在这篇文章中，我们看了一下ScribeJava提供的最有用的现成类。

We learned how to handle OAuth 1.0 and OAuth 2.0 flows with external APIs. We also learned how to configure the library in order to use our own APIs.

我们学习了如何处理与外部API的OAuth 1.0和OAuth 2.0流程。我们还学习了如何配置库，以便使用我们自己的API。

As usual, all code samples shown in this tutorial are available over on GitHub.

像往常一样，本教程中显示的所有代码样本都可以在GitHub上找到。