# API [![PkgGoDev](https://pkg.go.dev/badge/github.com/SevereCloud/vksdk/v2/api)](https://pkg.go.dev/github.com/SevereCloud/vksdk/v2/api) [![VK](https://img.shields.io/badge/developers-%234a76a8.svg?logo=VK&logoColor=white)](https://dev.vk.com/ru/api/getting-started) Данная библиотека поддерживает версию API **5.131**. ## Запросы В начале необходимо инициализировать api с помощью [ключа доступа](https://dev.vk.com/ru/api/access-token/getting-started): ```go vk := api.NewVK("") ``` ### Запросы к 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://dev.vk.com/method/users.get) ```go users, err := vk.UsersGet(api.Params{ "user_ids": 1, }) if err != nil { log.Fatal(err) } ``` ### Параметры [![PkgGoDev](https://pkg.go.dev/badge/github.com/SevereCloud/vksdk/v2/api/params)](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) ``` ### Обработка ошибок [![VK](https://img.shields.io/badge/developers-%234a76a8.svg?logo=VK&logoColor=white)](https://dev.vk.com/ru/reference/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` ### Поддержка MessagePack и zstd > Результат перехода с gzip (JSON) на zstd (msgpack): > > - в 7 раз быстрее сжатие (–1 мкс); > - на 10% меньше размер данных (8 Кбайт вместо 9 Кбайт); > - продуктовый эффект не статзначимый :( > > [Как мы отказались от JPEG, JSON, TCP и ускорили ВКонтакте в два раза](https://habr.com/ru/company/vk/blog/594633/) VK API способно возвращать ответ в виде [MessagePack](https://msgpack.org/). Это эффективный формат двоичной сериализации, похожий на JSON, только быстрее и меньше по размеру. ВНИМАНИЕ, C MessagePack НЕКОТОРЫЕ МЕТОДЫ МОГУТ ВОЗВРАЩАТЬ СЛОМАННУЮ КОДИРОВКУ. Для сжатия, вместо классического gzip, можно использовать [zstd](https://github.com/facebook/zstd). Сейчас vksdk поддерживает zstd без словаря. Если кто знает как получать словарь, [отпишитесь сюда](https://github.com/SevereCloud/vksdk/issues/180). ```go vk := api.NewVK(os.Getenv("USER_TOKEN")) method := "store.getStickersKeywords" params := api.Params{ "aliases": true, "all_products": true, "need_stickers": true, } r, err := vk.Request(method, params) // Content-Length: 44758 if err != nil { log.Fatal(err) } log.Println("json:", len(r)) // json: 814231 vk.EnableMessagePack() // Включаем поддержку MessagePack vk.EnableZstd() // Включаем поддержку zstd r, err = vk.Request(method, params) // Content-Length: 35755 if err != nil { log.Fatal(err) } log.Println("msgpack:", len(r)) // msgpack: 650775 ``` ### Запрос любого метода Пример запроса [users.get](https://dev.vk.com/method/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 [![PkgGoDev](https://pkg.go.dev/badge/github.com/SevereCloud/vksdk/v2/errors)](https://pkg.go.dev/github.com/SevereCloud/vksdk/v2/api#VK.Execute) [![VK](https://img.shields.io/badge/developers-%234a76a8.svg?logo=VK&logoColor=white)](https://dev.vk.com/ru/method/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://dev.vk.com/ru/method/ads). Максимальное число обращений к методам секции 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 [![VK](https://img.shields.io/badge/developers-%234a76a8.svg?logo=VK&logoColor=white)](https://dev.vk.com/ru/api/captcha-error) Если какое-либо действие (например, отправка сообщения) выполняется пользователем слишком часто, то запрос к API может возвращать ошибку "Captcha needed". При этом пользователю понадобится ввести код с изображения и отправить запрос повторно с передачей введенного кода Captcha в параметрах запроса. **Код ошибки**: 14 **Текст ошибки**: Captcha needed Если возникает данная ошибка, то в сообщении об ошибке передаются также следующие параметры: - `err.CaptchaSID` - идентификатор captcha - `err.CaptchaImg` - ссылка на изображение, которое нужно показать пользователю, чтобы он ввел текст с этого изображения. В этом случае следует запросить пользователя ввести текст с изображения `err.CaptchaImg` и повторить запрос, добавив в него параметры: - `captcha_sid` - полученный идентификатор - `captcha_key` - текст, который ввел пользователь ## Загрузка файлов [![VK](https://img.shields.io/badge/developers-%234a76a8.svg?logo=VK&logoColor=white)](https://dev.vk.com/ru/api/upload/overview) ### 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://dev.vk.com/method/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://dev.vk.com/method/stories.getPhotoUploadServer) ```go uploadInfo, err = vk.UploadStoriesPhoto(params, file) ``` Загрузить историю с видео. [Параметры](https://dev.vk.com/method/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://dev.vk.com/method/leadForms.create) и [leadForms.edit](https://dev.vk.com/method/leadForms.edit). Полученные данные можно использовать в методах [prettyCards.create](https://dev.vk.com/method/prettyCards.create) и [prettyCards.edit](https://dev.vk.com/method/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) } ```