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.
