1. Требования
2. Зависимости
3. Актуальная версия
4. Подготовка к использованию
5. Логирование
6. Инициализация
7. Авторизация
    7.1. Authorization Code Flow для пользователя
    7.2. Authorization Code Flow для сообщества
    7.3. Обработка ошибки need_validation
    7.4. Client Credentials Flow
8. Запросы к API
    8.1. Запрос от имени пользователя
    8.2. Запрос к открытому методу
    8.3. Запрос с универсальными параметрами
    8.4. Публикация фотографии на стене пользователя
9. Execute-запросы
10. Обработка ошибок
11. Обработка событий Callback API
12. Получение данных Streaming API
    12.1. Инициализация
    12.2. Добавление правила
    12.3. Получение правил
    12.4. Удаление правила
    12.5. Чтение потока
13. Пример использования

Страница проекта на Github: https://github.com/VKCOM/vk-java-sdk

Java-библиотека для взаимодействия с API ВКонтакте, упрощающая внедрение OAuth-авторизации и вызов методов API.

Эта библиотека была создана с использованием VK API JSON Schema. Страница проекта на Github: здесь. В схеме используется версия API 5.73.

• JDK версии 1.8 или выше
• Gradle версии 2.13 или выше

В проекте используются:

• Apache Http Client версии 4.5.2
• SLF4J версии 1.7.22
• Apache Commons Lang версии 3.5
• Apache Commons Collections версии 4.1
• Apache Commons IO версии 2.5
• Google Gson версии 2.8.1

Актуальный релиз — 0.5.12, от 27 февраля 2018 года.

Подключение зависимости в Maven:

<dependency>
  <groupId>com.vk.api</groupId>
  <artifactId>sdk</artifactId>
  <version>0.5.12</version>
</dependency>

Подключение зависимости в Gradle:

dependencies {
  compile 'com.vk.api:sdk:0.5.12'
}

Создайте приложение ВКонтакте на этой странице. Выберите подходящий тип.

Укажите название, подтвердите действие по SMS. Вы будете перенаправлены на страницу с настройками.

В дальнейшем Вам потребуются ID приложения (в документации обозначается как API_ID), секретный ключ (CLIENT_SECRET) и доверенный redirect URI (REDIRECT_URI).

Библиотека использует SLF4J для логирования. Чтобы включить логирование, нужно добавить привязку для конкретного фреймворка логирования. Подробнее в документации SLF4J.
Maven:

<dependencies>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-jdk14</artifactId>
        <version>1.7.22</version>
    </dependency>
</dependencies>

Gradle:

dependencies {
    compile group: 'org.slf4j', name: 'slf4j-jdk14', version: '1.7.22'
}

Добавить конфигурационый файл src/main/resources/logging.properties:

.level=INFO
handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINEST
deng.level=FINEST

Установить системную переменную, указывающую путь до файла:

-Djava.util.logging.config.file=logging.properties

Maven:

<dependencies>

<dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-slf4j-impl</artifactId>
      <version>2.7</version>
    </dependency>

<dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-api</artifactId>
      <version>2.7</version>
    </dependency>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
      <version>2.7</version>
    </dependency>
</dependencies>

Gradle:

dependencies {
    //Binding for Log4J -->
    compile group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl', version: '2.7'

//Log4j API and Core implementation required for binding
    compile group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.7'
    compile group: 'org.apache.logging.log4j', name: 'log4j-core', version: '2.7'
}

Добавить конфигурационый файл src/main/resources/log4j2.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<Configuration status="info">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n"/>
        </Console>
    </Appenders>

<Loggers>
        <Root level="info">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

Создайте объект VkApiClient следующим образом:

TransportClient transportClient = HttpTransportClient.getInstance();
VkApiClient vk = new VkApiClient(transportClient);

Обратите внимание, Вы можете использовать транспортный клиент по своему выбору. Мы используем Apache Http Client.

Библиотека предусматривает несколько способов авторизации, основанных на реализации OAuth 2.0 в API ВКонтакте. Пожалуйста, ознакомьтесь с документацией, прежде чем начать.

Authorization Code Flow позволяет вызывать методы API с серверной стороны.

Эта схема авторизации состоит из двух этапов — получение авторизационного кода ("code") и обмен его на ключ доступа ("access_token"). Сначала Вам необходимо получить "code" (инструкция), а затем выполнить второй этап:

UserAuthResponse authResponse = vk.oAuth()
    .userAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)
    .execute();

UserActor actor = new UserActor(authResponse.getUserId(), authResponse.getAccessToken());

Метод принимает в качестве параметров ID приложения, секретный ключ, redirect URI, список прав доступа и "code", полученный на первом этапе.

После успешного выполнения будет создан объект UserActor. Вы можете обращаться к API ВКонтакте от имени пользователя.

Отличие этой схемы от предыдущей заключается в том, что Вам необходимо передавать параметр groupId, чтобы получить ключ доступа сообщества. Пожалуйста, прочитайте подробное руководство.

GroupAuthResponse authResponse = vk.oAuth()
    .groupAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)
    .execute();

GroupActor actor = new GroupActor(groupId, authResponse.getAccessTokens().get(groupId));

После успешного выполнения будет создан объект GroupActor. Вы можете обращаться к API ВКонтакте от имени сообщества.

В процессе авторизации Вы можете получить ошибку "need_validation. Используйте такой код для ее обработки:

try {
    UserAuthResponse authResponse = vk.oAuth()
        .userAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)
        .execute();
} catch (OAuthException e) {
    e.getRedirectUri();
}

UserActor actor = new UserActor(authResponse.getUserId(), authResponse.getAccessToken());

Эта схема позволяет получить ключ доступа для работы с методами секции secure. Обратите внимание, ключ привязан к IP и не подходит для работы с другими методами. Мы рекомендуем использовать сервисный ключ из настроек приложения.
 

ServiceClientCredentialsFlowResponse authResponse = vk.oAuth()
    .serviceClientCredentialsFlow(APP_ID, CLIENT_SECRET)
    .execute();

ServiceActor actor = new ServiceActor(APP_ID, CLIENT_SECRET, authResponse.getAccessToken());

После успешного выполнения будет создан объект ServiceActor.

Полный список методов API Вы можете найти на этой странице.

GetResponse getResponse = vk.wall().get(actor)
    .ownerId(1)
    .count(100)
    .offset(5)
    .filter("owner")
    .execute();

List<UserXtrCounters> users = vk.users().get(actor)
    .userIds("1")
    .fields(UserField.VERIFIED, UserField.SEX)
    .lang(Lang.EN)
    .execute();

Полный список параметров Вы можете найти здесь.

PhotoUpload serverResponse = vk.photos().getWallUploadServer(actor).execute();
WallUploadResponse uploadResponse = vk.upload().photoWall(serverResponse.getUploadUrl(), file).execute();
List<Photo> photoList = vk.photos().saveWallPhoto(actor, uploadResponse.getPhoto())
     .server(uploadResponse.getServer())
     .hash(uploadResponse.getHash())
     .execute();

Photo photo = photoList.get(0);
String attachId = "photo" + photo.getOwnerId() + "_" + photo.getId();
GetResponse getResponse = vk.wall().post(actor)
    .attachments(attachId)
    .execute();

Подробная информация о методе execute доступна здесь.
JsonElement response = vk.execute().code(actor, "return API.wall.get({"count": 1})")
    .execute();

JsonElement response = vk.execute().storageFunction(actor, "foo")
    .funcV(2) // set storage function version
    .unsafeParam("user_id", 1) // set storage function argument
    .execute();

JsonElement response = vk.execute().batch(actor,
        vk.database().getChairs(1).count(10),
        vk.database().getCities(1),
        vk.groups().getMembers(actor).groupId(groupId)
).execute();

try {
    vk.wall().post(actor)
        .message("Hello world")
        .execute();
} catch (ApiWallLinksForbiddenException e) {
    // Links posting is prohibited
} catch (ApiException e) {
    // Business logic error
} catch (ClientException e) {
    // Transport layer error
}

String captchaSid = null;
String captchaImg = null;

try {
    vk.wall().post(actor).message("Hello world").execute();
} catch (ApiCaptchaException e) {
    captchaSid = e.getCaptchaSid();
    captchaImg = e.getCaptchaImg();
}

//Show captcha image...

if (captchaImg != null) {
    vk.wall().post(actor)
        .message("Hello world")
        .captchaSid(captchaSid)
        .captchaKey(captchaKey)
        .execute();
}

Переопределите методы из класса CallbackApi, чтобы обрабатывать события:

public class CallbackApiHandler extends CallbackApi {
  @Override
  public void messageNew(Integer groupId, Message message) {
    System.out.println(message.getBody());
  }
}

...
CallbackApiHandler callbackApiHandler = new CallbackApiHandler();

String body = httpRequest.getBody();
callbackApiHandler.parse(body);

//Init clients
TransportClient transportClient = new HttpTransportClient();

VkApiClient vkClient = new VkApiClient(transportClient);
VkStreamingApiClient streamingClient = new VkStreamingApiClient(transportClient);

//Create service actor
Integer appId = 4123123;
String accessToken = "sadf0asfsadfas";
ServiceActor actor = new ServiceActor(appId, accessToken);

//Get streaming actor
GetServerUrlResponse getServerUrlResponse = vkClient.streaming().getServerUrl(actor).execute();
StreamingActor actor = new StreamingActor(getServerUrlResponse.getEndpoint(), getServerUrlResponse.getKey());

String tag = "1";
String value = "ok";

StreamingResponse response = streamingClient.rules().add(actor, tag, value).execute();

StreamingGetRulesResponse response = streamingClient.rules().get(actor).execute();

String tag = "1";
streamingClient.rules().delete(actor, tag).execute();

streamingClient.stream().get(actor, new StreamingEventHandler() {
    @Override
    public void handle(StreamingCallbackMessage message) {
        System.out.println(message);
    }
}).execute();

Бот для Youtrack: https://github.com/VKCOM/vk-java-sdk/wiki/YouTrack-bot