MyChat Integration API для Oracle PL/SQL
Інструкція зі встановлення та використання

Призначення
===========

Ці файли встановлюють в Oracle PL/SQL пакет MYCHAT_API для надсилання повідомлень у MyChat через REST Integration API.

Поки реалізовано дві операції:

1. Надсилання приватного повідомлення користувачу.
2. Надсилання повідомлення в текстову конференцію.

Звичайному користувачу не потрібно редагувати SQL-файли. Усі значення вводяться під час запуску.


Які файли мають бути в папці прикладу
=====================================

Мінімальний набір файлів:

install_mychat_api.cmd
detect_oracle_pdb_connect.ps1
00_install_all.sql
00_skip_examples.sql
01_admin_setup.sql
02_install_package.sql
03_examples.sql
readme_ru.txt
readme_en.txt
readme_ua.txt

Усі ці файли мають лежати в одній папці.

Призначення файлів:

install_mychat_api.cmd
  Головний файл запуску. Користувач запускає саме його.

detect_oracle_pdb_connect.ps1
  Автоматично визначає рядок підключення до локальної Oracle PDB через lsnrctl status.

00_install_all.sql
  Загальний сценарій встановлення. Підключається під SYS, запускає адміністративний скрипт, потім підключається під створеною схемою і встановлює пакет.

00_skip_examples.sql
  Заглушка для випадку, коли користувач не хоче надсилати тестові повідомлення.

01_admin_setup.sql
  Створює окрему схему Oracle, видає права і налаштовує ACL для доступу до MyChat-сервера.

02_install_package.sql
  Створює пакет MYCHAT_API.

03_examples.sql
  Надсилає тестове приватне повідомлення і тестове повідомлення в конференцію.

readme_ru.txt
  Інструкція російською мовою.

readme_en.txt
  Інструкція англійською мовою.

readme_ua.txt
  Інструкція українською мовою.

Запуск:

install_mychat_api.cmd


Що потрібно заздалегідь
=======================

1. Oracle Database встановлено і запущено.
2. SQL*Plus доступний із консолі командою sqlplus.
3. Oracle listener запущено.
4. Є пароль користувача SYS для потрібної PDB.
5. Є адреса MyChat-сервера, наприклад myserver.com.
6. Є ключ Integration API з налаштувань MyChat Server.
7. Із машини з Oracle є HTTPS-доступ до MyChat-сервера.


Найпростіший спосіб встановлення
================================

1. Відкрити консоль Windows у папці з цими файлами.

2. Виконати:

install_mychat_api.cmd

3. Скрипт увімкне UTF-8 для SQL*Plus і спробує сам знайти рядок підключення до локальної Oracle PDB через lsnrctl status.

Якщо скрипт покаже знайдений рядок підключення і запитає:

Use this connection string? [Y/n]:

натиснути Enter.

Якщо рядок підключення не знайдено автоматично, скрипт попросить ввести його вручну:

Oracle PDB connection string:

Формат рядка підключення:

host:port/service_name

Наприклад, це може бути адреса і сервіс, які показує lsnrctl status. Не можна копіювати текст у кутових дужках з інструкції. Кутові дужки означають, що туди потрібно підставити своє значення.


Що запитуватиме встановлювач
============================

1. SYS password for this PDB:

Ввести пароль користувача SYS для потрібної PDB.

2. Oracle schema for MyChat package [MYCHAT_API_USER]:

Можна просто натиснути Enter. Тоді буде створено окрему схему MYCHAT_API_USER.

Важливо: не вказувати тут робочу схему застосунку з потрібними таблицями. Вказана схема перестворюється.

3. Password for this Oracle schema:

Ввести пароль для нової схеми. Цей пароль потрібен лише для створеної схеми пакета.

4. MyChat host for ACL, without protocol, for example myserver.com:

Ввести host MyChat-сервера без https:// і без шляху /API/.

Приклад:

myserver.com

5. MyChat HTTPS port [443]:

Зазвичай просто натиснути Enter.

6. MyChat base URL, for example https://myserver.com:

Ввести базовий URL MyChat-сервера з https://, але без /API/ у кінці.

Приклад:

https://myserver.com

7. MyChat Integration API key:

Ввести ключ Integration API.

8. Integration name [oracle-plsql]:

Можна просто натиснути Enter.

9. HTTP timeout seconds [15]:

Можна просто натиснути Enter.

10. Send test messages now? [Y/n]:

Якщо потрібно одразу перевірити надсилання, натиснути Enter.
Якщо тестові повідомлення надсилати не потрібно, ввести n і натиснути Enter.


Тестові повідомлення
====================

Якщо вибрано надсилання тестових повідомлень, скрипт запитає:

1. Private message receiver UIN/nick/email [2]:

Ввести ID користувача, нік або email отримувача приватного повідомлення.

2. Private message text:

Ввести текст приватного повідомлення.

3. Conference UID [1]:

Ввести UID текстової конференції.

4. Conference message text:

Ввести текст повідомлення в конференцію.

Після успішного надсилання повідомлення мають з'явитися в MyChat, а SQL*Plus покаже відповідь API.


Як надіслати повідомлення вручну після встановлення
===================================================

Якщо SQL*Plus уже відкрито і підключено під схемою, де встановлено пакет MYCHAT_API, можна виконати SQL-запити нижче.

Приватне повідомлення:

select dbms_lob.substr(
         mychat_api.send_private_message(
           p_user_to => '2',
           p_msg     => 'Тестове повідомлення з Oracle PL/SQL'
         ),
         4000,
         1
       ) as response
from dual;

У цьому прикладі замінити:

'2' - на ID, нік або email отримувача;
'Тестове повідомлення з Oracle PL/SQL' - на свій текст.


Повідомлення в текстову конференцію:

select dbms_lob.substr(
         mychat_api.send_conference_message(
           p_uid => 1,
           p_msg => 'Тестове повідомлення з Oracle PL/SQL'
         ),
         4000,
         1
       ) as response
from dual;

У цьому прикладі замінити:

1 - на UID конференції;
'Тестове повідомлення з Oracle PL/SQL' - на свій текст.

Якщо в тексті є одинарна лапка, її потрібно написати двома лапками.

Приклад:

p_msg => 'It''s OK'


Як використовувати пакет з іншої схеми Oracle
=============================================

Якщо застосунок працює під іншою схемою Oracle, власник пакета має видати їй право на виконання:

grant execute on mychat_api to <APP_SCHEMA>;

Тут <APP_SCHEMA> потрібно замінити на ім'я схеми застосунку.

Після цього застосунок може викликати пакет із зазначенням власника:

MYCHAT_API_USER.mychat_api.send_private_message(...)

або:

MYCHAT_API_USER.mychat_api.send_conference_message(...)

Якщо під час встановлення було вибрано інше ім'я схеми замість MYCHAT_API_USER, використовуйте це ім'я.


Ручне встановлення без install_mychat_api.cmd
=============================================

Цей спосіб потрібен, якщо запускний CMD-файл використовувати не можна.

1. У консолі Windows виконати:

chcp 65001
set NLS_LANG=.AL32UTF8
sqlplus /nolog

2. Підключитися адміністратором Oracle:

connect sys@<рядок_підключення_до_PDB> as sysdba

Важливо: <рядок_підключення_до_PDB> замінити на реальний рядок підключення. Не копіювати кутові дужки.

3. Запустити адміністративний скрипт:

@01_admin_setup.sql

4. Підключитися створеною схемою:

connect <створена_схема>/<пароль>@<рядок_підключення_до_PDB>

5. Встановити пакет:

@02_install_package.sql

6. За потреби надіслати тестові повідомлення:

@03_examples.sql

Кожну команду потрібно вводити окремим рядком. Не можна вставляти connect і @скрипти одним довгим рядком.


Як дізнатися рядок підключення до PDB
=====================================

Для локальної Oracle Free можна виконати:

lsnrctl status

У виводі знайти:

1. HOST і PORT у розділі Listening Endpoints Summary.
2. Сервіс PDB у розділі Services Summary. Зазвичай він називається freepdb1.

Рядок підключення збирається так:

HOST:PORT/service_name

Перевірити рядок можна командою:

tnsping HOST:PORT/service_name

Якщо tnsping пише OK, цей рядок можна використовувати в connect.


Типові помилки
==============

ORA-12541: Cannot connect. No listener

SQL*Plus не бачить Oracle listener за вказаною адресою і портом. Перевірити lsnrctl status і використовувати HOST, PORT та service name з виводу listener-а.


SP2-0306: Invalid option

Зазвичай означає, що кілька команд вставили в один рядок. Наприклад, connect і @01_admin_setup.sql не можна писати одним рядком. Кожну команду вводити окремо.


SP2-0310: unable to open file

SQL*Plus запущено не з папки з SQL-файлами. Відкрити консоль у папці з файлами встановлення або запускати @скрипт із повним шляхом до файлу.


ORA-24247: network access denied by access control list

Oracle не дозволяє схемі пакета мережевий доступ до MyChat-сервера. Запустити 01_admin_setup.sql під SYS AS SYSDBA і вказати правильний MyChat host та порт.


ORA-01031: insufficient privileges

Недостатньо прав. Адміністративний скрипт 01_admin_setup.sql має запускатися під SYS AS SYSDBA у потрібній PDB.


Кракозябри замість тексту

Пакет надсилає JSON у UTF-8. Якщо текст уже потрапив в Oracle пошкодженим, пакет не зможе його відновити.

Для Windows SQL*Plus перед запуском sqlplus обов'язково виконати:

chcp 65001
set NLS_LANG=.AL32UTF8

SQL-файли мають бути збережені в UTF-8.


Що робить встановлювач всередині
================================

1. Створює окрему Oracle-схему для пакета.
2. Видає їй права create session і create procedure.
3. Видає права на sys.utl_http, sys.utl_i18n і sys.utl_raw.
4. Налаштовує Oracle ACL для доступу до MyChat-сервера.
5. Створює пакет MYCHAT_API.
6. Зберігає всередині пакета базовий URL MyChat, ключ Integration API, ім'я інтеграції та HTTP timeout.

Пакет надсилає запити методом POST на:

<MyChat base URL>/API/

Тіло запиту формується як JSON через стандартну функцію Oracle json_object.
