Java SDK

Страница Java SDK на Github: https://github.com/VKCOM/vk-java-sdk.

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

Эта библиотека была создана с использованием VK API JSON Schema. Страница проекта JSON-схема на Github: https://github.com/VKCOM/vk-api-schema. В схеме используется версия API – 5.131.

Требования

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

Зависимости

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

•
Apache Http Client версии 4.5.8.
•
SLF4J версии 1.7.26.
•
Apache Commons Lang версии 3.6.
•
Apache Commons Collections версии 4.3.
•
Apache Commons IO версии 2.6.
•
Google Gson версии 2.8.5.

Актуальная версия

Актуальный релиз.

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

maven

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

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

gradle

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

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

sbtlibraryDependencies += "com.vk.api" % "sdk" % "LATEST_VERSION"

Подготовка к использованию

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

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

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

Логирование

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

JDK Logger

Maven:

maven

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

Gradle:

Gradle

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

Добавьте файл logging.properties с конфигурацией (расположен в src/main/resources)

Java

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

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

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

log4j2

Maven:

maven

<dependencies>
    <!-- Binding for Log4J -->
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-slf4j-impl</artifactId>
      <version>2.11.2</version>
    </dependency>
    
    <!-- Log4j API and Core implementation required for binding -->
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-api</artifactId>
      <version>2.11.2</version>
    </dependency>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
      <version>2.11.2</version>
    </dependency>
</dependencies>

Gradle:

gradle

dependencies {
    //Binding for Log4J -->
    compile group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl', version: '2.11.2'
    
    //Log4j API and Core implementation required for binding
    compile group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.11.2'
    compile group: 'org.apache.logging.log4j', name: 'log4j-core', version: '2.11.2'
}

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

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 следующим образом:

Java

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

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

Авторизация

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

Authorization Code Flow для пользователя

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

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

Java

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 ВКонтакте от имени пользователя.

Authorization Code Flow для сообщества

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

Java

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`

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

Java

UserAuthResponse authResponse;
try {
    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());

Client Credentials Flow

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

Java

ServiceClientCredentialsFlowResponse authResponse = vk.oAuth()
    .serviceClientCredentialsFlow(APP_ID, CLIENT_SECRET)
    .execute();
    
ServiceActor actor = new ServiceActor(APP_ID, authResponse.getAccessToken());

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

Запросы к API

Полный список методов API.

Запрос от имени пользователя

Java

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

Запрос с универсальными параметрами

Java

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

Полный список параметров.

Публикация фотографии на стене пользователя

Java

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-запросы

Подробная информация о методе execute.

Использование `code`

Java

JsonElement response = vk.execute().code(actor, "return API.wall.get({\"count\": 1})")
    .execute();

Хранимая процедура

Java

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

Пакетные запросы

Java

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

Обработка ошибок

Общий случай

Java

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
}

Капча

Java

String captchaSid = null;
String captchaImg = null;

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

//Showing captcha image...

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

Обработка событий Callback API

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

Java

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

Обработка событий Callback API Long Poll

Включите Callback API Long Poll для нужного сообщества и выберите события, за которыми хотите следить.

Java

HttpTransportClient httpClient = HttpTransportClient.getInstance();
VkApiClient vk = new VkApiClient(httpClient);
vk.groups().setLongPollSettings(groupActor).enabled(true)
                                           .wallPostNew(true)
                                           .messageNew(true)
                                           .execute();

Переопределите методы из класса CallbackApiLongPoll, чтобы обрабатывать события, и создайте нужный конструктор:

Java

public class CallbackApiLongPollHandler extends CallbackApiLongPoll {
    public CallbackApiLongPollHandler(VkApiClient client, UserActor actor, Integer groupId) {
      super(client, actor, groupId);
    }

    public CallbackApiLongPollHandler(VkApiClient client, GroupActor actor) {
      super(client, actor);
    }

    @Override
    public void messageNew(Integer groupId, Message message) {
      System.out.println("messageNew: " + message.toString());
    }

    @Override
    public void wallPostNew(Integer groupId, WallPost wallPost) {
      System.out.println("wallPostNew: " + wallPost.toString());
    }
}

Чтобы использовать созданный CallbackApiLongPollHandler, который переопределяет методы из CallBackApiLongPoll, необходимо создать его экземпляр и вызвать метод run

Java

CallbackApiLongPollHandler handler = new CallbackApiLongPollHandler(vk, groupActor);
handler.run();

Пример использования Callback API Long Poll можно найти в разделе examples как group-bot, который логирует все события.

Получение данных Streaming API

Инициализация Streaming API

Java

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

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

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

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

Добавление правила

Java

//Create rule
String tag = "1";
String value = "ok";

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

Получение правил

Java

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

Удаление правила

Java

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

Чтение потока

Имплементируйте метод из класса StreamingEventHandler для обработки потоковых событий

Java

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

Примеры использования

В качестве примера использования SDK мы выпустили бота YouTrack.

Java SDK

Требования

Зависимости

Актуальная версия

Подготовка к использованию

Логирование

JDK Logger

log4j2

Инициализация

Авторизация

Authorization Code Flow для пользователя

Authorization Code Flow для сообщества

Обработка ошибки need_validation

Client Credentials Flow

Запросы к API

Запрос от имени пользователя

Запрос с универсальными параметрами

Публикация фотографии на стене пользователя

Execute-запросы

Использование code

Хранимая процедура

Пакетные запросы

Обработка ошибок

Общий случай

Капча

Обработка событий Callback API

Обработка событий Callback API Long Poll

Получение данных Streaming API

Инициализация Streaming API

Добавление правила

Получение правил

Удаление правила

Чтение потока

Примеры использования

Обработка ошибки `need_validation`

Использование `code`