|
|
# API
|
|
|
|
|
|
[](https://pkg.go.dev/github.com/SevereCloud/vksdk/v2/api)
|
|
|
[](https://vk.com/dev/first_guide)
|
|
|
|
|
|
Данная библиотека поддерживает версию API **5.122**.
|
|
|
|
|
|
## Запросы
|
|
|
|
|
|
В начале необходимо инициализировать api с помощью [ключа доступа](https://vk.com/dev/access_token):
|
|
|
|
|
|
```go
|
|
|
vk := api.NewVK("<TOKEN>")
|
|
|
```
|
|
|
|
|
|
### Запросы к API
|
|
|
|
|
|
- `users.get` -> `vk.UsersGet(api.Params{})`
|
|
|
- `groups.get` с extended=1 -> `vk.GroupsGetExtended(api.Params{})`
|
|
|
|
|
|
Список всех методов можно найти на
|
|
|
[данной странице](https://pkg.go.dev/github.com/SevereCloud/vksdk/v2/api?tab=doc#VK).
|
|
|
|
|
|
Пример запроса [`users.get`](https://vk.com/dev/users.get)
|
|
|
|
|
|
```go
|
|
|
users, err := vk.UsersGet(api.Params{
|
|
|
"user_ids": 1,
|
|
|
})
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### Параметры
|
|
|
|
|
|
[](https://pkg.go.dev/github.com/SevereCloud/vksdk/v2/api/params)
|
|
|
|
|
|
Модуль params предназначен для генерации параметров запроса.
|
|
|
|
|
|
```go
|
|
|
// import "github.com/SevereCloud/vksdk/v2/api/params"
|
|
|
|
|
|
b := params.NewMessageSendBuilder()
|
|
|
b.PeerID(123)
|
|
|
b.Random(0)
|
|
|
b.DontParseLinks(false)
|
|
|
b.Message("Test message")
|
|
|
|
|
|
res, err = api.MessageSend(b.Params)
|
|
|
```
|
|
|
|
|
|
### Обработка ошибок
|
|
|
|
|
|
[](https://vk.com/dev/errors)
|
|
|
|
|
|
Обработка ошибок полностью поддерживает методы
|
|
|
[go 1.13](https://blog.golang.org/go1.13-errors)
|
|
|
|
|
|
```go
|
|
|
if errors.Is(err, api.ErrAuth) {
|
|
|
log.Println("User authorization failed")
|
|
|
}
|
|
|
```
|
|
|
|
|
|
```go
|
|
|
var e *api.Error
|
|
|
if errors.As(err, &e) {
|
|
|
switch e.Code {
|
|
|
case api.ErrCaptcha:
|
|
|
log.Println("Требуется ввод кода с картинки (Captcha)")
|
|
|
log.Printf("sid %s img %s", e.CaptchaSID, e.CaptchaImg)
|
|
|
case 1:
|
|
|
log.Println("Код ошибки 1")
|
|
|
default:
|
|
|
log.Printf("Ошибка %d %s", e.Code, e.Text)
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Для Execute существует отдельная ошибка `ExecuteErrors`
|
|
|
|
|
|
### Запрос любого метода
|
|
|
|
|
|
Пример запроса [users.get](https://vk.com/dev/users.get)
|
|
|
|
|
|
```go
|
|
|
// Определяем структуру, которую вернет API
|
|
|
var response []object.UsersUser
|
|
|
var err api.Error
|
|
|
|
|
|
params := api.Params{
|
|
|
"user_ids": 1,
|
|
|
}
|
|
|
|
|
|
// Делаем запрос
|
|
|
err = vk.RequestUnmarshal("users.get", &response, params)
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
|
|
|
log.Print(response)
|
|
|
```
|
|
|
|
|
|
### Execute
|
|
|
|
|
|
[](https://pkg.go.dev/github.com/SevereCloud/vksdk/v2/api#VK.Execute)
|
|
|
[](https://vk.com/dev/execute)
|
|
|
|
|
|
Универсальный метод, который позволяет запускать последовательность других
|
|
|
методов, сохраняя и фильтруя промежуточные результаты.
|
|
|
|
|
|
```go
|
|
|
var response struct {
|
|
|
Text string `json:"text"`
|
|
|
}
|
|
|
|
|
|
err = vk.Execute(`return {text: "hello"};`, &response)
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
|
|
|
log.Print(response.Text)
|
|
|
```
|
|
|
|
|
|
### Обработчик запросов
|
|
|
|
|
|
Обработчик `vk.Handler` должен возвращать структуру ответа от VK API и ошибку.
|
|
|
В качестве параметров принимать название метода и параметры.
|
|
|
|
|
|
```go
|
|
|
vk.Handler = func(method string, params ...api.Params) (api.Response, error) {
|
|
|
// ...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Это может потребоваться, если вы можете поставить свой обработчик с
|
|
|
[fasthttp](https://github.com/valyala/fasthttp) и логгером.
|
|
|
|
|
|
Стандартный обработчик использует [encoding/json](https://pkg.go.dev/net/http)
|
|
|
и [net/http](https://pkg.go.dev/net/http). В стандартном обработчике можно
|
|
|
настроить ограничитель запросов и HTTP клиент.
|
|
|
|
|
|
#### Ограничитель запросов
|
|
|
|
|
|
К методам API ВКонтакте (за исключением методов из секций secure и ads) с
|
|
|
ключом доступа пользователя или сервисным ключом доступа можно обращаться не
|
|
|
чаще 3 раз в секунду. Для ключа доступа сообщества ограничение составляет 20
|
|
|
запросов в секунду. Если логика Вашего приложения подразумевает вызов
|
|
|
нескольких методов подряд, имеет смысл обратить внимание на метод execute. Он
|
|
|
позволяет совершить до 25 обращений к разным методам в рамках одного запроса.
|
|
|
|
|
|
Для методов секции ads действуют собственные ограничения, ознакомиться с ними
|
|
|
Вы можете на [этой странице](https://vk.com/dev/ads_limits).
|
|
|
|
|
|
Максимальное число обращений к методам секции secure зависит от числа
|
|
|
пользователей, установивших приложение. Если приложение установило меньше 10
|
|
|
000 человек, то можно совершать 5 запросов в секунду, до 100 000 — 8 запросов,
|
|
|
до 1 000 000 — 20 запросов, больше 1 млн. — 35 запросов в секунду.
|
|
|
|
|
|
Если Вы превысите частотное ограничение, сервер вернет ошибку с кодом
|
|
|
**6: "Too many requests per second."**.
|
|
|
|
|
|
С помощью параметра `vk.Limit` можно установить ограничение на определенное
|
|
|
количество запросов в секунду
|
|
|
|
|
|
### HTTP client
|
|
|
|
|
|
В модуле реализована возможность изменять HTTP клиент с помощью параметра
|
|
|
`vk.Client`
|
|
|
|
|
|
Пример прокси
|
|
|
|
|
|
```go
|
|
|
|
|
|
dialer, _ := proxy.SOCKS5("tcp", "127.0.0.1:9050", nil, proxy.Direct)
|
|
|
httpTransport := &http.Transport{
|
|
|
Dial: dialer.Dial,
|
|
|
}
|
|
|
httpTransport.Dial = dialer.Dial
|
|
|
|
|
|
client := &http.Client{
|
|
|
Transport: httpTransport,
|
|
|
}
|
|
|
|
|
|
vk.Client = client
|
|
|
```
|
|
|
|
|
|
### Ошибка с Captcha
|
|
|
|
|
|
[](https://vk.com/dev/captcha_error)
|
|
|
|
|
|
Если какое-либо действие (например, отправка сообщения) выполняется
|
|
|
пользователем слишком часто, то запрос к API может возвращать ошибку
|
|
|
"Captcha needed". При этом пользователю понадобится ввести код с изображения
|
|
|
и отправить запрос повторно с передачей введенного кода Captcha в параметрах
|
|
|
запроса.
|
|
|
|
|
|
**Код ошибки**: 14
|
|
|
**Текст ошибки**: Captcha needed
|
|
|
|
|
|
Если возникает данная ошибка, то в сообщении об ошибке передаются также
|
|
|
следующие параметры:
|
|
|
|
|
|
- `err.CaptchaSID` - идентификатор captcha
|
|
|
- `err.CaptchaImg` - ссылка на изображение, которое нужно показать
|
|
|
пользователю, чтобы он ввел текст с этого изображения.
|
|
|
|
|
|
В этом случае следует запросить пользователя ввести текст с изображения
|
|
|
`err.CaptchaImg` и повторить запрос, добавив в него параметры:
|
|
|
|
|
|
- `captcha_sid` - полученный идентификатор
|
|
|
- `captcha_key` - текст, который ввел пользователь
|
|
|
|
|
|
## Загрузка файлов
|
|
|
|
|
|
[](https://vk.com/dev/upload_files)
|
|
|
|
|
|
### 1. Загрузка фотографий в альбом
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Файл объемом не более 50 МБ, соотношение сторон не менее 1:20
|
|
|
|
|
|
Загрузка фотографий в альбом для текущего пользователя:
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadPhoto(albumID, response.Body)
|
|
|
```
|
|
|
|
|
|
Загрузка фотографий в альбом для группы:
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadPhotoGroup(groupID, albumID, response.Body)
|
|
|
```
|
|
|
|
|
|
### 2. Загрузка фотографий на стену
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Файл объемом не более 50 МБ, соотношение сторон не менее 1:20
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadWallPhoto(response.Body)
|
|
|
```
|
|
|
|
|
|
Загрузка фотографий в альбом для группы:
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadWallPhotoGroup(groupID, response.Body)
|
|
|
```
|
|
|
|
|
|
### 3. Загрузка главной фотографии пользователя или сообщества
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: размер не менее 200x200px, соотношение сторон от 0.25 до 3,
|
|
|
сумма высоты и ширины не более 14000px, файл объемом не более 50 МБ,
|
|
|
соотношение сторон не менее 1:20.
|
|
|
|
|
|
Загрузка главной фотографии пользователя
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadUserPhoto(file)
|
|
|
```
|
|
|
|
|
|
Загрузка фотографии пользователя или сообщества с миниатюрой
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadOwnerPhoto(ownerID, squareСrop,file)
|
|
|
```
|
|
|
|
|
|
Для загрузки главной фотографии сообщества необходимо передать его идентификатор
|
|
|
со знаком «минус» в параметре `ownerID`.
|
|
|
|
|
|
Дополнительно Вы можете передать параметр `squareСrop` в формате "x,y,w" (без
|
|
|
кавычек), где x и y — координаты верхнего правого угла миниатюры, а w — сторона
|
|
|
квадрата. Тогда для фотографии также будет подготовлена квадратная миниатюра.
|
|
|
|
|
|
Загрузка фотографии пользователя или сообщества без миниатюры:
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadOwnerPhoto(ownerID, "", file)
|
|
|
```
|
|
|
|
|
|
### 4. Загрузка фотографии в личное сообщение
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: сумма высоты и ширины не более 14000px, файл объемом
|
|
|
не более 50 МБ, соотношение сторон не менее 1:20.
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadMessagesPhoto(peerID, file)
|
|
|
```
|
|
|
|
|
|
### 5. Загрузка главной фотографии для чата
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: размер не менее 200x200px, соотношение сторон от 0.25 до 3, сумма
|
|
|
высоты и ширины не более 14000px, файл объемом не более 50 МБ, соотношение
|
|
|
сторон не менее 1:20.
|
|
|
|
|
|
Без обрезки:
|
|
|
|
|
|
```go
|
|
|
messageInfo, err = vk.UploadChatPhoto(peerID, file)
|
|
|
```
|
|
|
|
|
|
С обрезкой:
|
|
|
|
|
|
```go
|
|
|
messageInfo, err = vk.UploadChatPhotoCrop(peerID, cropX, cropY, cropWidth, file)
|
|
|
```
|
|
|
|
|
|
### 6. Загрузка фотографии для товара
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: минимальный размер фото — 400x400px, сумма высоты и ширины
|
|
|
не более 14000px, файл объемом не более 50 МБ, соотношение сторон не менее 1:20.
|
|
|
|
|
|
Если Вы хотите загрузить основную фотографию товара, необходимо передать
|
|
|
параметр `mainPhoto = true`. Если фотография не основная, она не будет обрезаться.
|
|
|
|
|
|
Без обрезки:
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadMarketPhoto(groupID, mainPhoto, file)
|
|
|
```
|
|
|
|
|
|
Основную фотографию с обрезкой:
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadMarketPhotoCrop(groupID, cropX, cropY, cropWidth, file)
|
|
|
```
|
|
|
|
|
|
### 7. Загрузка фотографии для подборки товаров
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: минимальный размер фото — 1280x720px, сумма высоты и ширины
|
|
|
не более 14000px, файл объемом не более 50 МБ, соотношение сторон не менее 1:20.
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadMarketAlbumPhoto(groupID, file)
|
|
|
```
|
|
|
|
|
|
### 9. Загрузка видеозаписей
|
|
|
|
|
|
Допустимые форматы: AVI, MP4, 3GP, MPEG, MOV, MP3, FLV, WMV.
|
|
|
|
|
|
[Параметры](https://vk.com/dev/video.save)
|
|
|
|
|
|
```go
|
|
|
videoUploadResponse, err = vk.UploadVideo(params, file)
|
|
|
```
|
|
|
|
|
|
После загрузки видеозапись проходит обработку и в списке видеозаписей может
|
|
|
появиться спустя некоторое время.
|
|
|
|
|
|
### 10. Загрузка документов
|
|
|
|
|
|
Допустимые форматы: любые форматы за исключением mp3 и исполняемых файлов.
|
|
|
Ограничения: файл объемом не более 200 МБ.
|
|
|
|
|
|
`title` - название файла с расширением
|
|
|
|
|
|
`tags` - метки для поиска
|
|
|
|
|
|
`typeDoc` - тип документа.
|
|
|
|
|
|
- doc - обычный документ;
|
|
|
- audio_message - голосовое сообщение
|
|
|
|
|
|
Загрузить документ:
|
|
|
|
|
|
```go
|
|
|
docsDoc, err = vk.UploadDoc(title, tags, file)
|
|
|
```
|
|
|
|
|
|
Загрузить документ в группу:
|
|
|
|
|
|
```go
|
|
|
docsDoc, err = vk.UploadGroupDoc(groupID, title, tags, file)
|
|
|
```
|
|
|
|
|
|
Загрузить документ, для последующей отправки документа на стену:
|
|
|
|
|
|
```go
|
|
|
docsDoc, err = vk.UploadWallDoc(title, tags, file)
|
|
|
```
|
|
|
|
|
|
Загрузить документ в группу, для последующей отправки документа на стену:
|
|
|
|
|
|
```go
|
|
|
docsDoc, err = vk.UploadGroupWallDoc(groupID, title, tags, file)
|
|
|
```
|
|
|
|
|
|
Загрузить документ в личное сообщение:
|
|
|
|
|
|
```go
|
|
|
docsDoc, err = vk.UploadMessagesDoc(peerID, typeDoc, title, tags, file)
|
|
|
```
|
|
|
|
|
|
### 11. Загрузка обложки сообщества
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: минимальный размер фото — 795x200px, сумма высоты и ширины
|
|
|
не более 14000px, файл объемом не более 50 МБ. Рекомендуемый размер: 1590x400px.
|
|
|
В сутки можно загрузить не более 1500 обложек.
|
|
|
|
|
|
Необходимо указать координаты обрезки фотографии в параметрах
|
|
|
`cropX`, `cropY`, `cropX2`, `cropY2`.
|
|
|
|
|
|
```go
|
|
|
photo, err = vk.UploadOwnerCoverPhoto(groupID, cropX, cropY, cropX2, cropY2, file)
|
|
|
```
|
|
|
|
|
|
### 12. Загрузка аудиосообщения
|
|
|
|
|
|
Допустимые форматы: Ogg Opus.
|
|
|
Ограничения: sample rate 16kHz, variable bitrate 16 kbit/s, длительность
|
|
|
не более 5 минут.
|
|
|
|
|
|
```go
|
|
|
docsDoc, err = vk.UploadMessagesDoc(peerID, "audio_message", title, tags, file)
|
|
|
```
|
|
|
|
|
|
### 13. Загрузка истории
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: сумма высоты и ширины не более 14000px, файл объемом
|
|
|
не более 10МБ. Формат видео: h264 video, aac audio,
|
|
|
максимальное разрешение 720х1280, 30fps.
|
|
|
|
|
|
Загрузить историю с фотографией. [Параметры](https://vk.com/dev/stories.getPhotoUploadServer)
|
|
|
|
|
|
```go
|
|
|
uploadInfo, err = vk.UploadStoriesPhoto(params, file)
|
|
|
```
|
|
|
|
|
|
Загрузить историю с видео. [Параметры](https://vk.com/dev/stories.getVideoUploadServer)
|
|
|
|
|
|
```go
|
|
|
uploadInfo, err = vk.UploadStoriesVideo(params, file)
|
|
|
```
|
|
|
|
|
|
### Загрузка фоновой фотографии в опрос
|
|
|
|
|
|
Допустимые форматы: JPG, PNG, GIF.
|
|
|
Ограничения: сумма высоты и ширины не более 14000px, файл объемом не более 50 МБ,
|
|
|
соотношение сторон не менее 1:20.
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadPollsPhoto(file)
|
|
|
```
|
|
|
|
|
|
```go
|
|
|
photosPhoto, err = vk.UploadOwnerPollsPhoto(ownerID, file)
|
|
|
```
|
|
|
|
|
|
Для загрузки фотографии сообщества необходимо передать его идентификатор со
|
|
|
знаком «минус» в параметре `ownerID`.
|
|
|
|
|
|
### Загрузка фотографии для карточки
|
|
|
|
|
|
Для карточек используются квадратные изображения минимальным размером 400х400.
|
|
|
В случае загрузки неквадратного изображения, оно будет обрезано до квадратного.
|
|
|
Допустимые форматы: JPG, PNG, BMP, TIFF или GIF.
|
|
|
Ограничения: файл объемом не более 5 МБ.
|
|
|
|
|
|
```go
|
|
|
photo, err = vk.UploadPrettyCardsPhoto(file)
|
|
|
```
|
|
|
|
|
|
### Загрузка обложки для формы
|
|
|
|
|
|
Для форм сбора заявок используются прямоугольные изображения размером 1200х300.
|
|
|
В случае загрузки изображения другого размера, оно будет автоматически обрезано
|
|
|
до требуемого.
|
|
|
Допустимые форматы: JPG, PNG, BMP, TIFF или GIF.
|
|
|
Ограничения: файл объемом не более 5 МБ.
|
|
|
|
|
|
```go
|
|
|
photo, err = vk.UploadLeadFormsPhoto(file)
|
|
|
```
|
|
|
|
|
|
Полученные данные можно использовать в методах
|
|
|
[leadForms.create](https://vk.com/dev/leadForms.create)
|
|
|
и
|
|
|
[leadForms.edit](https://vk.com/dev/leadForms.edit).
|
|
|
|
|
|
Полученные данные можно использовать в методах
|
|
|
[prettyCards.create](https://vk.com/dev/prettyCards.create)
|
|
|
и
|
|
|
[prettyCards.edit](https://vk.com/dev/prettyCards.edit).
|
|
|
|
|
|
### Загрузки фотографии в коллекцию приложения для виджетов приложений сообществ
|
|
|
|
|
|
`imageType` (string) - тип изображения.
|
|
|
|
|
|
Возможные значения:
|
|
|
|
|
|
- 24x24
|
|
|
- 50x50
|
|
|
- 160x160
|
|
|
- 160x240
|
|
|
- 510x128
|
|
|
|
|
|
```go
|
|
|
image, err = vk.UploadAppImage(imageType, file)
|
|
|
```
|
|
|
|
|
|
### Загрузки фотографии в коллекцию сообщества для виджетов приложений сообществ
|
|
|
|
|
|
`imageType` (string) - тип изображения.
|
|
|
|
|
|
Возможные значения:
|
|
|
|
|
|
- 24x24
|
|
|
- 50x50
|
|
|
- 160x160
|
|
|
- 160x240
|
|
|
- 510x128
|
|
|
|
|
|
```go
|
|
|
image, err = vk.UploadGroupAppImage(imageType, file)
|
|
|
```
|
|
|
|
|
|
#### Примеры
|
|
|
|
|
|
Загрузка фотографии в альбом:
|
|
|
|
|
|
```go
|
|
|
response, err := os.Open("photo.jpeg")
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
defer response.Body.Close()
|
|
|
|
|
|
photo, err = vk.UploadPhoto(albumID, response.Body)
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Загрузка фотографии в альбом из интернета:
|
|
|
|
|
|
```go
|
|
|
response, err := http.Get("https://sun9-45.userapi.com/c638629/v638629852/2afba/o-dvykjSIB4.jpg")
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
defer response.Body.Close()
|
|
|
|
|
|
photo, err = vk.UploadPhoto(albumID, response.Body)
|
|
|
if err != nil {
|
|
|
log.Fatal(err)
|
|
|
}
|
|
|
```
|