diff --git a/docs/ru/md/Instructions/Airtable.md b/docs/ru/md/Instructions/Airtable.md new file mode 100644 index 0000000000..a29921a60f --- /dev/null +++ b/docs/ru/md/Instructions/Airtable.md @@ -0,0 +1,24 @@ +--- +id: Airtable +sidebar_class_name: Airtable +--- + + + +# Airtable + +Этот раздел посвящен библиотеке для работы с Airtable API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +1. Авторизуйтесь в Airtable и перейдите **[на страницу создания персональных токенов](https://airtable.com/create/tokens)**, нажмите **Create new token** + +![BF](../../static/img/Docs/Airtable/1.png) + +2. Введите название для нового токена, выберите из перечня необходимые **Scopes** (разрешения) и **Access** (базы и рабочие пространства, к которым у токена будет доступ) + +![BF](../../static/img/Docs/Airtable/2.png) + +3. Скопируйте новый **токен** + +![BF](../../static/img/Docs/Airtable/3.png) diff --git a/docs/ru/md/Instructions/Bitrix24.md b/docs/ru/md/Instructions/Bitrix24.md new file mode 100644 index 0000000000..5d411cfd91 --- /dev/null +++ b/docs/ru/md/Instructions/Bitrix24.md @@ -0,0 +1,62 @@ +--- +id: Bitrix24 +sidebar_class_name: Bitrix24 +--- + + + +# Bitrix24 + +Этот раздел посвящен библиотеке для работы с Bitrix24 API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +Работать и Bitrix24 через API можно двумя способами: через **Webhook** и через **локальное приложение**. Для обоих вариантов необходимо: + +1. Перейти в подраздел **Разработчикам** в разделе **Приложения** боковой панели + +![BF](../../static/img/Docs/Bitrix24/1.png) + +2. Выбрать пункт **Другое** + +![BF](../../static/img/Docs/Bitrix24/2.png) + +

+ +### Для работы через Webhook + +1. Выберите пункт **Входящий вебхук** + +![BF](../../static/img/Docs/Bitrix24/3.png) + +2. Заполните необходимые разрешения в **Настройках прав** и сохраните URL вебхука. Он будет использоваться для выполнения методов библиотеки как параметр **URL**. Необязательный параметр **Токен** в данном случае будет всегда оставаться пустым + +![BF](../../static/img/Docs/Bitrix24/4.png) + +

+ +## Для работы через Локальное приложение + +1. Выберите пункт **Локальное приложение** + +![BF](../../static/img/Docs/Bitrix24/5.png) + +2. Выберите путь обработчика (если приложение не подразумевает авторизацию других пользователей, но только управление Bitrix через один аккаунт администратора, то можно выбрать любой адрес, например https://localhost), поставьте галочку **Использует только API** (если необходим только функционал вызова методов библиотеки) и заполните необходимые права + +![BF](../../static/img/Docs/Bitrix24/6.png) + +3. Сохраните **ключ** и **код** приложения + +![BF](../../static/img/Docs/Bitrix24/7.png) + +4. При помощи ключа приложения вызовите функцию **ПолучитьСсылкуАвторизацииПриложения** и перейдите по полученной ссылке в браузере. После авторизации, скопируйте полученный код из адресной строки (или получите его на обработчик, адрес которого был указан в пункте 2) + +![BF](../../static/img/Docs/Bitrix24/8.png) + +5. Передайте полученный код, вместе с ключем и секретом приложения, в функцию **ПолучитьТокен**. Сохраните полученные **access** и **refresh токены** + +6. Время жизни токенов ограничено. Для получение нового токена можно воспользоваться функцией **ОбновитьТокен**, передав тутда refresh токен, ключ и секрет приложения. При обновлении создается не только новый access токен, но и refresh токен тоже + + + + diff --git a/docs/ru/md/Instructions/Dropbox.md b/docs/ru/md/Instructions/Dropbox.md new file mode 100644 index 0000000000..942a258035 --- /dev/null +++ b/docs/ru/md/Instructions/Dropbox.md @@ -0,0 +1,40 @@ +--- +id: Dropbox +sidebar_class_name: Dropbox +--- + + + +# Dropbox + +Этот раздел посвящен библиотеке для работы с Dropbox API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +1. Войдите в свой аккаунт на сайте [Dropbox Developers](https://www.dropbox.com/developers) + +![BF](../../static/img/Docs/Dropbox/1.png) + +1. Перейдите к **App Console** + +![BF](../../static/img/Docs/Dropbox/2.png) + +2. Нажмите **Create app** + +![BF](../../static/img/Docs/Dropbox/3.png) + +4. Введите имя нового приложения и выберите **Full Dropbox** + +![BF](../../static/img/Docs/Dropbox/4.png) + +5. После создания, на странице приложения нажмите **Scoped app** и выберите разрешения, которые необходимы для решения ваших задач. Сохраните **AppKey** и **AppSecret** + +![BF](../../static/img/Docs/Dropbox/5.png) + +6. Получите ссылку авторизации при помощи функции *ПолучитьСсылкуАвторизации(Знач КлючПриложения)* и передите по ней в браузере + +![BF](../../static/img/Docs/Dropbox/6.png) + +7. Передайте **полученный код**, **AppKey** и **AppSecret** в функцию *ПолучитьТокен(Знач КлючПриложения, Знач СекретПриложения, Знач Код)*, сохраните полученные **access_token** и **refresh_token** + +8. По истечении времени жизни access_token, его можно обновить при помощи функции *ОбновитьТокен(Знач КлючПриложения, Знач СекретПриложения, Знач РефрешТокен)* \ No newline at end of file diff --git a/docs/ru/md/Instructions/Google_Calendar.md b/docs/ru/md/Instructions/Google_Calendar.md new file mode 100644 index 0000000000..df45dc229e --- /dev/null +++ b/docs/ru/md/Instructions/Google_Calendar.md @@ -0,0 +1,98 @@ +--- +id: GoogleCalendar +sidebar_class_name: GoogleCalendar +--- + + + +# Google Календарь + +Этот раздел посвящен библиотеке для работы с API Google Calendar. На данной странице описаны все действия, необходимые для полноценного начала работы + +:::important +Если вы уже используете ОПИ для работы с другими сервисами Google Workspase и выполняли стартовую настройку, то пункты **Создание проекта** и **Настройка OAuth** можно пропустить. Необходимо лишь **включить сервис Google Drive** в своем проекте и **заново получить токен** (последние два пункта инструкции). +::: + +## Начало работы + +
+ +### Создание проекта + +1. Перейдите на [главную страницу Google Cloud](https://console.cloud.google.com) и создайте проект + +![BF](../../static/img/Docs/GoogleCalendar/1.png) + +2. Выберите созданный проект и в боковом меню перейдите APIs and Services -> OAuth consent screen + +![BF](../../static/img/Docs/GoogleCalendar/2.png) + +3. Выберите пункт External + +![BF](../../static/img/Docs/GoogleCalendar/3.png) + +4. Заполните поля App name, User support email и Email addresses (все поля со звездочками) + +![BF](../../static/img/Docs/GoogleCalendar/4.png) + +5. Нажимайте далее и Save and continue на последней вкладке + +![BF](../../static/img/Docs/GoogleCalendar/5.png) + +6. Нажмите Publish App + +![BF](../../static/img/Docs/GoogleCalendar/6.png) + +
+ +### Настройка OAuth + +1. В боковом меню выберите пункт Credentials -> Create Credentials -> OAuth client ID + +![BF](../../static/img/Docs/GoogleCalendar/7.png) + +2. Введите имя и выберите Application type - Desktop app + +![BF](../../static/img/Docs/GoogleCalendar/8.png) + +3. Сохраните ClientID и Client Secret + +![BF](../../static/img/Docs/GoogleCalendar/9.png) + +
+ +### Включение сервиса Google Calendar + +1. Перейдите на [страницу Календаря в Marketplace](https://console.cloud.google.com/marketplace/product/google/calendar-json.googleapis.com) + +2. Нажмите Enable + +![BF](../../static/img/Docs/GoogleCalendar/12.png) + +
+ +### Получение Токена + +1. Передайте ClientID в функцию OPI_GoogleWorkspace.СформироватьСсылкуПолученияКода() с булево параметрами используемых вами сервисов. Результатом функции будет URL, который необходимо открыть в браузере. Авторизуйтесь при помощи своего аккаунта Google + +![BF](../../static/img/Docs/GoogleCalendar/10.png) + +2. Скопируйте код из URL после авторизации + +![BF](../../static/img/Docs/GoogleCalendar/11.png) + +3. Используйте полученный код, ClientID и Client Secret для вызова функции OPI_GoogleWorkspace.ПолучитьТокенПоКоду(ClientID, ClientSecret, Code) + +```json title="Результат функции ПолучитьТокенПоКоду(), если перевести его в JSON" + +{ + "token_type": "Bearer", + "refresh_token": "1//09au6OES3JN9oCgYIARAAGAkSNwF-L9Ir1B7uawfwafT1wE0FKO519Xj6JxawfawfyjMyJ_QlUZYLHZqw", + "scope": "https://www.googleapis.com/auth/calendar", + "expires_in": 3599, + "access_token": "ya29.a0AfB_byA344tXkIawdawdwadadhyZQV8bSZn_snNXtY2HLb7l71awdawdawdad-ASgpzyOSWIvEmPruhUa_1yCCq6jvoD0r_q-fNEsARrH8zpJ3c6LNGWvwdg8CXsSxYaCgYKAWkSawfwafawfrCK0EP5kZY_A0171" +} + +``` + +4. Используйте **access_token** для передачи в качестве параметра Токен при вызове функций библиотеки, а refresh_token - для получения нового access_token (функция OPI_GoogleWorkspace.ОбновитьТокен(ClientID, ClientSecret, RefreshToken)), когда время жизни старого истечет. При обновлении токена refresh_token не обновляется - вы можете использовать его один и тот же для получения нового access_token каждый раз. diff --git a/docs/ru/md/Instructions/Google_Drive.md b/docs/ru/md/Instructions/Google_Drive.md new file mode 100644 index 0000000000..8d897ad8bf --- /dev/null +++ b/docs/ru/md/Instructions/Google_Drive.md @@ -0,0 +1,98 @@ +--- +id: GoogleDrive +sidebar_class_name: GoogleDrive +--- + + + +# Google Drive + +Этот раздел посвящен библиотеке для работы с API Google Drive. На данной странице описаны все действия, необходимые для полноценного начала работы + +:::important +Если вы уже используете ОПИ для работы с другими сервисами Google Workspase и выполняли стартовую настройку, то пункты **Создание проекта** и **Настройка OAuth** можно пропустить. Необходимо лишь **включить сервис Google Drive** в своем проекте и **заново получить токен** (последние два пункта инструкции). +::: + +## Начало работы + +
+ +### Создание проекта + +1. Перейдите на [главную страницу Google Cloud](https://console.cloud.google.com) и создайте проект + +![BF](../../static/img/Docs/GoogleCalendar/1.png) + +2. Выберите созданный проект и в боковом меню перейдите APIs and Services -> OAuth consent screen + +![BF](../../static/img/Docs/GoogleCalendar/2.png) + +3. Выберите пункт External + +![BF](../../static/img/Docs/GoogleCalendar/3.png) + +4. Заполните поля App name, User support email и Email addresses (все поля со звездочками) + +![BF](../../static/img/Docs/GoogleCalendar/4.png) + +5. Нажимайте далее и Save and continue на последней вкладке + +![BF](../../static/img/Docs/GoogleCalendar/5.png) + +6. Нажмите Publish App + +![BF](../../static/img/Docs/GoogleCalendar/6.png) + +
+ +### Настройка OAuth + +1. В боковом меню выберите пункт Credentials -> Create Credentials -> OAuth client ID + +![BF](../../static/img/Docs/GoogleCalendar/7.png) + +2. Введите имя и выберите Application type - Desktop app + +![BF](../../static/img/Docs/GoogleCalendar/8.png) + +3. Сохраните ClientID и Client Secret + +![BF](../../static/img/Docs/GoogleCalendar/9.png) + +
+ +### Включение сервиса Google Drive + +1. Перейдите на [страницу Drive в Marketplace](https://console.cloud.google.com/marketplace/product/google/drive.googleapis.com) + +2. Нажмите Enable + +![BF](../../static/img/Docs/GoogleDrive/1.png) + +
+ +### Получение Токена + +1. Передайте ClientID в функцию OPI_GoogleWorkspace.СформироватьСсылкуПолученияКода() с булево параметрами используемых вами сервисов. Результатом функции будет URL, который необходимо открыть в браузере. Авторизуйтесь при помощи своего аккаунта Google + +![BF](../../static/img/Docs/GoogleCalendar/10.png) + +2. Скопируйте код из URL после авторизации + +![BF](../../static/img/Docs/GoogleCalendar/11.png) + +3. Используйте полученный код, ClientID и Client Secret для вызова функции OPI_GoogleWorkspace.ПолучитьТокенПоКоду(ClientID, ClientSecret, Code) + +```json title="Результат функции ПолучитьТокенПоКоду(), если перевести его в JSON" + +{ + "token_type": "Bearer", + "refresh_token": "1//09au6OES3JN9oCgYIARAAGAkSNwF-L9Ir1B7uawfwafT1wE0FKO519Xj6JxawfawfyjMyJ_QlUZYLHZqw", + "scope": "https://www.googleapis.com/auth/...", + "expires_in": 3599, + "access_token": "ya29.a0AfB_byA344tXkIawdawdwadadhyZQV8bSZn_snNXtY2HLb7l71awdawdawdad-ASgpzyOSWIvEmPruhUa_1yCCq6jvoD0r_q-fNEsARrH8zpJ3c6LNGWvwdg8CXsSxYaCgYKAWkSawfwafawfrCK0EP5kZY_A0171" +} + +``` + +4. Используйте **access_token** для передачи в качестве параметра Токен при вызове функций библиотеки, а refresh_token - для получения нового access_token (функция OPI_GoogleWorkspace.ОбновитьТокен(ClientID, ClientSecret, RefreshToken)), когда время жизни старого истечет. При обновлении токена refresh_token не обновляется - вы можете использовать его один и тот же для получения нового access_token каждый раз. diff --git a/docs/ru/md/Instructions/Google_Sheets.md b/docs/ru/md/Instructions/Google_Sheets.md new file mode 100644 index 0000000000..28c96aa9d8 --- /dev/null +++ b/docs/ru/md/Instructions/Google_Sheets.md @@ -0,0 +1,98 @@ +--- +id: GoogleSheets +sidebar_class_name: GoogleSheets +--- + + + +# Google Sheets + +Этот раздел посвящен библиотеке для работы с API Google Sheets. На данной странице описаны все действия, необходимые для полноценного начала работы + +:::important +Если вы уже используете ОПИ для работы с другими сервисами Google Workspase и выполняли стартовую настройку, то пункты **Создание проекта** и **Настройка OAuth** можно пропустить. Необходимо лишь **включить сервис Google Sheets** в своем проекте и **заново получить токен** (последние два пункта инструкции). +::: + +## Начало работы + +
+ +### Создание проекта + +1. Перейдите на [главную страницу Google Cloud](https://console.cloud.google.com) и создайте проект + +![BF](../../static/img/Docs/GoogleCalendar/1.png) + +2. Выберите созданный проект и в боковом меню перейдите APIs and Services -> OAuth consent screen + +![BF](../../static/img/Docs/GoogleCalendar/2.png) + +3. Выберите пункт External + +![BF](../../static/img/Docs/GoogleCalendar/3.png) + +4. Заполните поля App name, User support email и Email addresses (все поля со звездочками) + +![BF](../../static/img/Docs/GoogleCalendar/4.png) + +5. Нажимайте далее и Save and continue на последней вкладке + +![BF](../../static/img/Docs/GoogleCalendar/5.png) + +6. Нажмите Publish App + +![BF](../../static/img/Docs/GoogleCalendar/6.png) + +
+ +### Настройка OAuth + +1. В боковом меню выберите пункт Credentials -> Create Credentials -> OAuth client ID + +![BF](../../static/img/Docs/GoogleCalendar/7.png) + +2. Введите имя и выберите Application type - Desktop app + +![BF](../../static/img/Docs/GoogleCalendar/8.png) + +3. Сохраните ClientID и Client Secret + +![BF](../../static/img/Docs/GoogleCalendar/9.png) + +
+ +### Включение сервиса Google Sheets + +1. Перейдите на [страницу Sheets в Marketplace](https://console.cloud.google.com/marketplace/product/google/sheets.googleapis.com) + +2. Нажмите Enable + +![BF](../../static/img/Docs/GoogleSheets/1.png) + +
+ +### Получение Токена + +1. Передайте ClientID в функцию OPI_GoogleWorkspace.СформироватьСсылкуПолученияКода() с булево параметрами используемых вами сервисов. Результатом функции будет URL, который необходимо открыть в браузере. Авторизуйтесь при помощи своего аккаунта Google + +![BF](../../static/img/Docs/GoogleCalendar/10.png) + +2. Скопируйте код из URL после авторизации + +![BF](../../static/img/Docs/GoogleCalendar/11.png) + +3. Используйте полученный код, ClientID и Client Secret для вызова функции OPI_GoogleWorkspace.ПолучитьТокенПоКоду(ClientID, ClientSecret, Code) + +```json title="Результат функции ПолучитьТокенПоКоду(), если перевести его в JSON" + +{ + "token_type": "Bearer", + "refresh_token": "1//09au6OES3JN9oCgYIARAAGAkSNwF-L9Ir1B7uawfwafT1wE0FKO519Xj6JxawfawfyjMyJ_QlUZYLHZqw", + "scope": "https://www.googleapis.com/auth/...", + "expires_in": 3599, + "access_token": "ya29.a0AfB_byA344tXkIawdawdwadadhyZQV8bSZn_snNXtY2HLb7l71awdawdawdad-ASgpzyOSWIvEmPruhUa_1yCCq6jvoD0r_q-fNEsARrH8zpJ3c6LNGWvwdg8CXsSxYaCgYKAWkSawfwafawfrCK0EP5kZY_A0171" +} + +``` + +4. Используйте **access_token** для передачи в качестве параметра Токен при вызове функций библиотеки, а refresh_token - для получения нового access_token (функция OPI_GoogleWorkspace.ОбновитьТокен(ClientID, ClientSecret, RefreshToken)), когда время жизни старого истечет. При обновлении токена refresh_token не обновляется - вы можете использовать его один и тот же для получения нового access_token каждый раз. diff --git a/docs/ru/md/Instructions/Notion.md b/docs/ru/md/Instructions/Notion.md new file mode 100644 index 0000000000..ceeacdd945 --- /dev/null +++ b/docs/ru/md/Instructions/Notion.md @@ -0,0 +1,38 @@ +--- +id: Notion +sidebar_class_name: Notion +--- + + + +# Notion + +Этот раздел посвящен библиотеке для работы с Notion API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +1. Перейдите **[в раздел интеграций портала для разработчиков](https://www.notion.so/my-integrations)** + +![BF](../../static/img/Docs/Notion/1.png) + +2. Введите название вашей интеграции + +![BF](../../static/img/Docs/Notion/2.png) + +3. После завершения создания интеграции, нажмите *Show* и скопируйте **Токен (Secret)** + +![BF](../../static/img/Docs/Notion/3.png) + +4. Перейдите в **[основной интерфейс Notion](https://notion.so)** и создайте новую страницу. Эта страница будет родительской для всех остальных объектов, создаваемых через API + +![BF](../../static/img/Docs/Notion/4.png) + +5. Нажмите три точки в правом верхнем углу и в самом низу найдите пункт *Add connections*. Выберите там свою интеграцию из пунктов 1-3 + +![BF](../../static/img/Docs/Notion/5.png) + +6. Получите ID этой страинцы. Это можно сделать нажав Share -> Copy link или просто скопировав из URL + +![BF](../../static/img/Docs/Notion/6.png) + +**Токен** и **ID страницы** - два параметра, необходимые для работы через API \ No newline at end of file diff --git a/docs/ru/md/Instructions/Slack.md b/docs/ru/md/Instructions/Slack.md new file mode 100644 index 0000000000..308614facb --- /dev/null +++ b/docs/ru/md/Instructions/Slack.md @@ -0,0 +1,64 @@ +--- +id: Slack +sidebar_class_name: Slack +--- + + + +# Slack + +Этот раздел посвящен библиотеке для работы со Slack Web API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +1. Войдите в свой аккаунт и перейдите на страницу **Your Apps** на сайте [Slack API](https://api.slack.com) + +![BF](../../static/img/Docs/Slack/1.png) + +
+ +2. Нажмите **Create App** и выберите пункт **From scratch** + +![BF](../../static/img/Docs/Slack/2.png) + +3. Выберите название и рабочую область, в которой необходимо создать приложение + +![BF](../../static/img/Docs/Slack/3.png) + +
+ +4. Создайте новый токен, нажав **Generate Token and Scopes** ниже на странице приложения + +![BF](../../static/img/Docs/Slack/4.png) + +
+ +5. Выберите имя и добавьте разрешения + +![BF](../../static/img/Docs/Slack/5.png) + +
+ +6. Перейдите в раздел **Premission scope** из пункта установки приложения + +![BF](../../static/img/Docs/Slack/6.png) + +
+ +7. Добавьте необходимые для ваших целей разрешения + +![BF](../../static/img/Docs/Slack/7.png) + +
+ +8. Установите приложение + +![BF](../../static/img/Docs/Slack/8.png) + +
+ +9. Сохраните сгенерированный токен + +![BF](../../static/img/Docs/Slack/9.png) + +
\ No newline at end of file diff --git a/docs/ru/md/Instructions/Start.md b/docs/ru/md/Instructions/Start.md new file mode 100644 index 0000000000..64b083885b --- /dev/null +++ b/docs/ru/md/Instructions/Start.md @@ -0,0 +1,62 @@ +--- +id: Start +sidebar_class_name: NachaloRaboty +--- + +# Добро пожаловать! + +![OPI](../../static/img/logo_long.png) + +**Открытый пакет интеграций** - набор инструментов для интеграции с некоторыми популярными API посредством CLI, 1C:Enterprise или OneScript. Он состоит из общих модулей, каждый из которых отвечает за свой API, а также нескольких модулей-инструментов, общих для всех. + +Реализованные методы выполняют конечные задачи (вроде *ОтправитьСообщение()* или *СоздатьПост()*), что позволяет использовать их без углубления в реализацию. Однако, код, при этом, достаточно сильно декомпозирован - методы авторизации, получения данных и пр. по возможности вынесены в отдельные функции. Это позволяет легко добавлять новые методы, даже если они еще не реализованы в самой библиотеке на текущий момент. + +
+ +Быстрый переход по документации: +
+ + + + + + + + + + + + +
+ +
+ +## Начало работы + +Релизы библиотеки выходят в пяти вариантах: + +- Как CLI приложение для Windows и Linux (exe, rpm, deb) +- Как XML файлы расширения для загрузки через конфигуратор +- Как EDT проект расширения +- Как отдельный файл расширения формата cfe +- Как OneScript пакет расширения ospx + +Вне зависимости от выбранного сопособа установки, получать файлы необходимо из [Release](https://github.com/Bayselonarrend/OpenIntegrations/releases), так как в самих файлах репозитория бывают промежуточные данные и функции, находящиеся в процессе разработки. + +Подробнее о каждом варианте релиза в разделе [Про варианты релизов](/docs/Start/Release-variants) + +
+ +## Структура модулей + +Общие модули проекта бывают двух видов: + +- Служебные + - OPI_Инструменты + - OPI_Криптография +- Модули непосредственной работы с API + - OPI_Telegram, OPI_VK... + +:::warning +Не рекомендуется использовать методы служебных модулей в других местах вашей конфигурации (если вы собираетесь обновляться до новых версий в дальнейшем). Для сохранения обратной совместимости, количество/назначение параметров и типы возвращаемых значений для методов работы с API не изменяются, но это не применимо к служебным модулям, которые могут изменяться как угодно для оптимизации и дополнения под новые нужды. Если вам необходим функционал из служебных модулей, рекомендуется скопировать его себе отдельно. +::: diff --git a/docs/ru/md/Instructions/Telegram.md b/docs/ru/md/Instructions/Telegram.md new file mode 100644 index 0000000000..80edeebb65 --- /dev/null +++ b/docs/ru/md/Instructions/Telegram.md @@ -0,0 +1,41 @@ +--- +id: Telegram +sidebar_class_name: Telegram +--- + + + +# Telegram + +Этот раздел посвящен библиотеке для работы с Telegram API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +- Создайте бота Telegram + + 1. Все действия при работе с Telegram API осуществляются посредством ботов. Для создания нового бота необходимо в мессенджере начать диалог с [@BotFather](https://t.me/BotFather) + + ![BF](../../static/img/Docs/Telegram/2.png) + + 2. Выбрать в меню команду */newbot* + + ![BF](../../static/img/Docs/Telegram/3.png) + + 3. BotFather предложит вам выбрать имя и никнейм бота, после чего процедура создания будет завершена + +- Сохраните **токен**, который вам прислал BotFather после завершения создания бота + + ![BF](../../static/img/Docs/Telegram/1.png) + +- (Дополнительно) Определитесь с целью взаимодействия + + Созданного вами бота теперь можно применить двумя способами + + - В качестве чат-бота + - Для автоматизации ведения канала + + В зависимости от выбранного способа примения будет отличаться способ получения **ID чата** - параметра, отвечающего за определение объекта взаимодействия. + + В случае с чат-ботом, ID чата будет являться ID пользователя, с которым бот осуществляет диалог. Если же бота необходимо использовать для ведения канала, то, после добавления его в качестве администратора, вместо ID чата можно использовать имя канала через @ (@MyChannel) + + Токен и ID чата являются основными параметрами всех методов работы с Telegram API \ No newline at end of file diff --git a/docs/ru/md/Instructions/Twitter.md b/docs/ru/md/Instructions/Twitter.md new file mode 100644 index 0000000000..efae7d6b47 --- /dev/null +++ b/docs/ru/md/Instructions/Twitter.md @@ -0,0 +1,120 @@ +--- +id: Twitter +sidebar_class_name: Twitter +--- + + + +# Twitter | X + +Этот раздел посвящен библиотеке для работы с Twitter API. На данной странице описаны все действия, необходимые для полноценного начала работы. Данная библиотека позволяет работать с функционалом бесплатного плана, т.е. создавать твиты. + +## Начало работы + + +Работа с Twitter подразумевает работу с двумя API - v1 (1.1) и v2, которые, при этом, не относятся к разным видам действий, но просто являются версиями друг друга. Несмотря на то, что Twitter настаивает на использовании v2, вышло так, что некоторые механизмы (в частности механизм загрузки файлов) в ней так и не появилися. Поэтому, даже для создания обычного твита с картинкой необходима работа с обеими версиями API, а, как следствие, двойной набор авторизационных данны. Этот набор описан в функции *ПолучитьСтандартныеПараметры()* + + +```bsl + + Параметры_.Вставить("redirect_uri" , ""); + Параметры_.Вставить("scope" , ""); + Параметры_.Вставить("client_id" , ""); + Параметры_.Вставить("client_secret" , ""); + Параметры_.Вставить("access_token" , ""); + Параметры_.Вставить("refresh_token" , ""); + Параметры_.Вставить("oauth_token" , ""); + Параметры_.Вставить("oauth_token_secret" , ""); + Параметры_.Вставить("oauth_consumer_key" , ""); + Параметры_.Вставить("oauth_consumer_secret", ""); + +``` + +Вы можете определить эти параметры прямо в структуре внутри данной функции или передавать непосредственно при вызове функций уже для работы с API - каждая из них принимает параметры последним необязательным параметром. При такой передаче стандартные параметры будут перезаписаны по ключам. Рассмотрим создание приложения и получение каждого поля + + + ### Создание приложения + Для работы с Twitter API необходимо перейти по адресу [https://developer.twitter.com/](https://developer.twitter.com/), зарегистрироваться и создать новое приложение + + ![BF](../../static/img/Docs/Twitter/1.png) + ![BF](../../static/img/Docs/Twitter/2.png) + ![BF](../../static/img/Docs/Twitter/3.png) + ![BF](../../static/img/Docs/Twitter/4.png) + ![BF](../../static/img/Docs/Twitter/5.png) + + ### Определение полей + После создания приложения можно заполнить необходимые данные в 1С + + + - **redirect_uri** + + redirect_uri - адрес обработчика http-запросов, указанный при регистрации. Авторизация API v2 требует подтверждения входа через браузер, после которого запрос со специальным кодом на данный обработчик должен будет прийти. Далее об этом будет в пункте access_token и refresh_token. + + + - **scope** + + scope определяет доступные для работы функции. В *ПолучитьСтандартныеПараметры()* список scope определен по умолчанию. + + - **client_id** + + ![BF](../../static/img/Docs/Twitter/6.png) + + - **client_secret** + + ![BF](../../static/img/Docs/Twitter/7.png) + + - **access_token** и **refresh_token** + + Эти токены необходимо получить http запросом с указанием кода, который приходит при авторизации на http-сервис redirect_uri. Порядок действий: + 1. Создать ссылку для авторизации в браузере при помощи функции *ПолучитьСсылкуАвторизации* + 2. Добавить в модуль http-сервиса (GET) вызов функции *ОбработкаВходящегоЗапросаПослеАвторизации*, передавая HTTPСервисЗапрос как параметр. + 3. Авторизоваться в браузере по ссылке из п.1. + 3. Сохранить access_token и refresh_token, полученный из функции *ОбработкаВходящегоЗапросаПослеАвторизации* п. 2, в константы или другое хранилище + + + ```bsl title="Получение" + + Функция Twitterget(Запрос) + + Код = Запрос.ПараметрыЗапроса["code"]; + ОтветТокен = OPI_Twitter.ПолучитьТокен(Код, Параметры); + + Константы.TwitterRefresh.Установить(ОтветТокен["refresh_token"]); + Константы.TwitterToken.Установить(ОтветТокен["access_token"]); + + Ответ = Новый HTTPСервисОтвет(200); + Возврат Ответ; + + КонецФункции + + ``` + + ```bsl title="Обновление" + + Процедура ОбновлятьТокенКаждыеДваЧаса(Знач Параметры) + + Ответ = OPI_Twitter.ОбновитьТокен(Параметры); + Константы.TwitterToken.Установить(Ответ["access_token"]); + Константы.TwitterRefresh.Установить(Ответ["refresh_token"]); + + КонецПроцедуры + ``` + + Хардкодить данные токены нельзя, так как acess_token действует всего 2 часа. По истечении этого времени, токен необходимо обновить функцией *ОбновитьТокен*. При этом обновляется как access_token, так и refresh_token. Т.е. при следующем обновлении сгоревшего acess_token токена, refresh_token должен быть из предыдущего запроса. + + ![BF](../../static/img/Docs/Twitter/8.png) + + + - **oauth_token** и **oauth_token_secret** + + ![BF](../../static/img/Docs/Twitter/9.png) + + - **oauth_consumer_key** и **oauth_consumer_secret** + + ![BF](../../static/img/Docs/Twitter/10.png) + + + После заполнения данных полей можно приступать к работе с методами API + + + \ No newline at end of file diff --git a/docs/ru/md/Instructions/VK.md b/docs/ru/md/Instructions/VK.md new file mode 100644 index 0000000000..f39029adb5 --- /dev/null +++ b/docs/ru/md/Instructions/VK.md @@ -0,0 +1,94 @@ +--- +id: VK +sidebar_class_name: VK +--- + + + +# ВКонтакте + +Этот раздел посвящен библиотеке для работы с VK API. Она заточена для работы с сообществами и выполнением действий от их имени. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +Для начала работы необходимо получить некоторые параметры для VK API. + +

+Перечень необходимых данных в виде структуры содержится в функции *ПолучитьСтандартныеПараметры()*. Вы можете указывать значения параметров прямо в ней или же передавать их структурой при вызове любых других методов библиотеки в качестве необязательного параметра *Параметры* (последний во всех методах билиотеки). В последнем случае стандартные параметры будут перезаписаны по ключам теми, которые переданы при вызове метода. Перезаписаны будут только совпадающие по ключам данные. Если какой то параметр есть в наборе стандартных, но не был передан при вызове метода, то он сохранит стандартное значение. +

+ + ```bsl + _Параметры = Новый Структура; + + _Параметры.Вставить("v" , "5.131"); + _Параметры.Вставить("from_group" , "1"); + _Параметры.Вставить("group_id" , "123456789"); + _Параметры.Вставить("owner_id" , "-123456789"); + _Параметры.Вставить("app_id" , "87654321"); + _Параметры.Вставить("access_token" , "vk1.a.E-byuFeG1qcN7..."); + + ``` + +Рассмотрим получение каждого значения: + +**1. v** + + Параметр `v` означает версию VK API. Тестирование проводилось на 5.131, рекомендуется его таким и оставить + +**2. from_group** + + От лица группы. Должен быть 1 + +**3. group_id и owner_id** + + ID группы. Если у вас стандартный адрес группы, то id можно найти в URL. В противном случае он будет на вкладке "Управление" в группе, под полем Адрес. owner_id - тоже самое, но со знаком '-' впереди + + ![BF](../../static/img/Docs/VK/1.png) + +**4. app_id** + + app_id - ID приложения. Для создания приложения необходимо: + + * Перейти по адресу https://id.vk.com/about/business/go, авторизоваться и ввести свои данные физ. или юр. лица + + ![BF](../../static/img/Docs/VK/2.png) + + * Ввести название приложения и выбрать пункт **Web** + + ![BF](../../static/img/Docs/VK/3.png) + + * Ввести домееное имя и URL обработчика перенаправлений. Тут нужно отметить, что данный механизм создания приложений - новый. Еще недавно приложения VK создавались иначе и иметь redirect_url для них было не нужно. На данный момент не совсем понятно, зачем он нужен нам для серверного приложения - просто такого понятия как серверное приложение у VK теперь нет. Теоретически, туда можно вписать что угодно - для работы с библиотекой в получении обратных данных нет необходимости. Однако, с течением времени, это может измениться. + + ![BF](../../static/img/Docs/VK/4.png) + + * Ввести паспортные данные или данные об организации, включить доступ к сообществам (короче, если у вас уже было приложение до этого, то вам крупно повезло, а если нет российского паспорта - придется писать в поддержку) + + ![BF](../../static/img/Docs/VK/8.png) + + * Получить app_id на странице приложения + + ![BF](../../static/img/Docs/VK/5.png) + +**5. access_token** + + Ссылку на получение acess_token можно получить при помощи функции *СоздатьСсылкуПолученияТокена* или склеить вручную: + + https://oauth.vk.com/authorize?client_id= + *app_id* + &scope=offline,wall,groups,photos,stats,stories,ads&v=5.131&response_type=token&redirect_uri=https://api.vk.com/blank.html + + * По этой ссылке необходимо перейти в браузере + * Авторизоваться через ВК и подтвердить доступ + * Забрать токен из параметра URL в адресной строке + + ![BF](../../static/img/Docs/VK/6.png) + +**(Дополнительно) communitytoken** + + Некоторые методы, например для работы с чат-ботом сообщества, принимают в качестве параметра communitytoken - в этих методах он заменяет access_token. Для его получения необходимо: + + * Зайти в раздел "Управление" в группе ВК + * Найти вкладку "Работа с API" + * Нажать "Создать ключ" и забрать его + + ![BF](../../static/img/Docs/VK/7.png) + + Пока вам не нужно использовать такие методы, получать communitytoken не обязательно \ No newline at end of file diff --git a/docs/ru/md/Instructions/Viber.md b/docs/ru/md/Instructions/Viber.md new file mode 100644 index 0000000000..2f9bd2008c --- /dev/null +++ b/docs/ru/md/Instructions/Viber.md @@ -0,0 +1,59 @@ +--- +id: Viber +sidebar_class_name: Viber +--- + + + +# Viber + +Этот раздел посвящен библиотеке для работы с Viber API. На данной странице описаны все действия, необходимые для полноценного начала работы + +:::warning +Начиная с 05.02.2024 данный способ создания ботов более недействителен: Rakuten отменил возможность создавать ботов бесплатно и теперь для работы с API необходимо проходить верификацию по коммерческой модели. Подробнее [тут](https://help.viber.com/hc/en-us/articles/15247629658525-Bot-commercial-model) +::: + +## Начало работы + +У Viber есть два REST API: один для работы с каналами, а второй - для чат-ботов. В обоих случаях основными параметрами служат **Токен** и **IDПользователя** + +- Если вам необходимо управлять каналом: + 1. Зайдите в приложение Viber и создайте новый канал + + ![BF](../../static/img/Docs/Viber/1.png) + + 2. После создания, перейдите в настройки канала -> Для разработчиков, и скопируйте **Токен** + + ![BF](../../static/img/Docs/Viber/2.png) + + 3. Установите Webhook. См. Установить Webhook + 4. **IDПользователя** - ваш ID (администратора канала). См. Получить информацию о канале + +
+ +- Если вам необходим чат-бот: + 1. Перейдите по ссылке [https://partners.viber.com/account/create-bot-account](https://partners.viber.com/account/create-bot-account) и авторизуйтесь с вашим номером телефона, который привязан к Viber + + ![BF](../../static/img/Docs/Viber/3.png) + + 2. Выберите пункт создания нового бота + + ![BF](../../static/img/Docs/Viber/4.png) + + 3. В меню создания бота заполните все необходимые поля + + ![BF](../../static/img/Docs/Viber/5.png) + + 4. Скопируйте **Токен** + + ![BF](../../static/img/Docs/Viber/6.png) + + 4. Найти своего нового бота вы можете отсканировав QR на странице создания или в настройках (пункт чат-боты) в приложении Viber. + + ![BF](../../static/img/Docs/Viber/7.png) + + 5. Сейчас вы не можете начать диалог с ботом, сначала необходимо установить Webhook. См. Установить Webhook + 6. После запуска **IDПользователя** будет ID конкретного человека, ведущего диалог с ботом. Получить можно из обработыки входящих сообщения по Webhook + + + **Важно:** ID одного и того же пользователя у чата и канала - это разные значения. Нельзя использовать ID, полученный из сообщения боту для вызова методов управления каналом и наоборот \ No newline at end of file diff --git a/docs/ru/md/Instructions/Yandex_Disk.md b/docs/ru/md/Instructions/Yandex_Disk.md new file mode 100644 index 0000000000..8934261fe0 --- /dev/null +++ b/docs/ru/md/Instructions/Yandex_Disk.md @@ -0,0 +1,62 @@ +--- +id: YandexDisk +sidebar_class_name: YandexDisk +--- + + + +# Яндекс Диск + +Этот раздел посвящен библиотеке для работы с Яндекс Диск API. На данной странице описаны все действия, необходимые для полноценного начала работы + +## Начало работы + +Для начала работы необходимо получить токен доступа к диску: + +1. Перейдите на [страницу создания приложения](https://oauth.yandex.ru/client/new/) + +![BF](../../static/img/Docs/YandexDisk/1.png) + +2. Введите название сервиса, выберите *Веб-сервисы* в качестве платформы. Redirect URI можно указать любой или выбрать пункт *Подставить URL для отладки* - для работы с библиотекой он не понадобится. + +![BF](../../static/img/Docs/YandexDisk/3.png) + +3. В поле *Доступ к данным* добавьте разрешения как на скриншоте ниже, после чего нажмите *Создать приложение* + +![BF](../../static/img/Docs/YandexDisk/2.png) + +4. Сохраните **ClientID** и **Client secret** со страницы приложения + +![BF](../../static/img/Docs/YandexDisk/4.png) + +5. Вызовите функцию *OPI_YandexID.ПолучитьКодПодтверждения()*, передав ClientID в качестве параметра. Она вернет ответ сервера Yandex, где будут поля: + - **user_code** - необходимо будет ввести в браузере + - **device_code** - необходимо будет передать в другую функцию + - **verification_url** - URL, который нужно открыть в браузере +
+ ```json title="Результат функции ПолучитьКодПодтверждения(), если перевести его в JSON" + { + "verification_url": "https://ya.ru/device", + "user_code": "gjehyruw", + "interval": 5, + "expires_in": 300, + "device_code": "12207cafec1b40ad8d0052af3faf0d12" + } + ``` + +6. Откройте URL из **verification_url** в барузере. Скорее всего это будет https://ya.ru/device. В появившееся поле введите **user_code** из пункта 5 + +![BF](../../static/img/Docs/YandexDisk/5.png) + +7. После ввода кода в пункте 6, вызовите функцию *OPI_YandexID.ПреобразоватьКодВТокен()*, передав туда **ClientID** и **ClientSecret** из пункта 4, а также **device_code** из пункта 5. Сохраните полученные **acess_token** и **refresh_token** + +```json title="Результат функции ПреобразоватьКодВТокен(), если перевести его в JSON" +{ + "token_type": "bearer", + "refresh_token": "1:Tj6nD2vgE2L8jwSm:YgWjQXPv6_y3e07GW70ig2AOyEXoRVsKKpApGHq2EOg7pfx0MKrXiCrfLBFtzgQawdawdwadad3Sasa9z2H0vSeZKNmZmA", + "expires_in": 31535956, + "access_token": "y0_AgAAAABWxxdkAAs0QgAAAAD59cawdawdwadadVKIiwGK__crw" +} +``` + +**acess_token** используется во всех остальных функциях библиотеки, а при помощи **refresh_token** его можно обновить, когда срок жизни будет подходить к концу (при помощи функции *ОбновитьТокен()*) \ No newline at end of file