1. Интеграция иесін белгілеңіз

Әкімші ретінде «Баптаулар → Қатынау → API клиенттері» ашыңыз. Әр сыртқы жүйе мен ортаға жеке клиент жасаңыз: сонда басқа арналарды тоқтатпай бір кілтті ауыстыруға немесе арнаны өшіруге болады. Танылатын атау мен иесі болатын пайдаланушыны көрсетіңіз. Кілт тек сол пайдаланушы құқықтары аясында жұмыс істейді.

Деректер қабылдау үшін «Жазу», ал күйлер, нәтижелер және жариялау түпкі нүктелері үшін «Оқу» таңдаңыз. Жазу тек иесі орындай алатын ағындарға, оқу — көре алатын ағындарға беріледі. Сұрау бойынша орындалатын жарияланым үшін иесінің орындау құқығы да қажет. Иесін өшіру немесе құқығын алу кілтке бірден әсер етеді.

2. Мерзімді, желілік қатынауды және жүктемені шектеңіз

Аяқталу күнін таңдаңыз: сол UTC күнінің соңына дейін жарамды, алдағы үш жылдан аспайды. Рұқсат етілген IPv4/IPv6 мекенжайларын немесе CIDR желілерін әр жолға біреуінен қосыңыз. IP қатынауы мен HMAC — тәуелсіз баптаулар: «Кез келген IP мекенжайы» IP сүзгісін өшіреді. Қол қою әдепкіде қосулы; әсіресе IP шектеулері болмаса, оны қосулы ұстау ұсынылады. Минутына сұраулар санын орнатыңыз. Бөлімнің жалпы API шегі де қолданылады.

Клиентті сақтап, жасалған кілтті қауіпсіз арнаңызбен беріңіз. Оны браузер кодына, ашық репозиторийге немесе URL ішіне салмаңыз. Кілтті Data Bridge жасайды; еркін жеке кілттер қолдау таппайды. Толық кілтті көрсету аудитке жазылады. Мысалдар мен сынақтар үшін орта айнымалысын пайдаланыңыз.

3. Нақты HTTP сұрауына қол қойыңыз

Кілтті мынада жіберіңіз: Authorization: Bearer ... немесе X-API-Key. HMAC үшін қосымша мыналар қажет: X-UBC-Timestamp — Unix секундтарымен және X-UBC-Signature: v1=<hex>. Клиент кілтімен HMAC-SHA256 есептеңіз: жаңа жолмен бөлінген төрт мән — уақыт белгісі, бас әріппен HTTP әдісі, сұрау параметрлері бар жол және нақты дене байттарының SHA-256 он алтылық хэші.

Сервермен уақыт айырмасы бес минуттан аспауы керек. Параметр ретін, кодтауды және орнату префиксін сақтаңыз. Қол қойғаннан кейін денені өзгертпеңіз: басқа пішімделген JSON басқа хэш береді. GET үшін бос байттардың хэшін есептеңіз. Құпия — кері хабарлау құпиясы емес, API клиентінің кілті.

4. Ping арқылы қатынауды тексеріңіз

requests орнатылған Python ортасында мынаны орнатыңыз: UBC_API_KEY және UBC_API_PING_URL. Соңғысы — мына бағыттың толық HTTPS мекенжайы: /api/v1/ping, қажетті префиксті қоса. Бұл мысал сұрауды қол қоюдан бұрын дайындайды, сондықтан нақты кодталған жолды пайдаланады; қайта бағыттаулар өшірулі.

import hashlib, hmac, os, time
from urllib.parse import urlsplit
import requests

key = os.environ["UBC_API_KEY"]
url = os.environ["UBC_API_PING_URL"]
request = requests.Request("GET", url).prepare()
body = request.body or b""
if isinstance(body, str):
    body = body.encode("utf-8")
parts = urlsplit(request.url)
path = parts.path + ("?" + parts.query if parts.query else "")
timestamp = str(int(time.time()))
canonical = "\n".join([
    timestamp, request.method, path,
    hashlib.sha256(body).hexdigest()
])
signature = hmac.new(key.encode("utf-8"),
                     canonical.encode("utf-8"),
                     hashlib.sha256).hexdigest()
request.headers.update({
    "Authorization": "Bearer " + key,
    "X-UBC-Timestamp": timestamp,
    "X-UBC-Signature": "v1=" + signature,
})
with requests.Session() as session:
    response = session.send(request, timeout=30,
                            allow_redirects=False)
    print(response.status_code, response.text)

Қайтарылған клиентті, сервер уақытын, аяқталу мерзімін және құқықтарды тексеріңіз. Содан кейін мынаны шақырыңыз: GET /api/v1/flows және тек келісілген ағындар қолжетімді екенін растаңыз. Мекенжай өзгерсе, жаңа қолтаңба қажет. POST үшін денені бір рет дайындап, оның байттарына қол қойыңыз және дәл сол байттарды жіберіңіз.

5. Қайталау, кілт ауыстыру және диагностика

Қолтаңба бір рет қабылданады: қайта қолдану мынаны қайтарады: 409 API_SIGNATURE_REPLAY. Әр күй сұрауы немесе жеткізілім қайталауы үшін қайта қол қойыңыз; мынаны ескеріңіз: Retry-After — бірдей GET сұрауын бір секунд ішінде қайталамау үшін. Жеткізілімнің мына мәнін сақтаңыз: Idempotency-Key: ол қайталама орындауға жол бермейді, ал HMAC әр жеке HTTP сұрауын қорғайды.

401 әдетте кілтке, мерзімге немесе қолтаңбаға қатысты; 403— IP не құқықтарға; 429— сұрау жиілігі шектеріне. Нақты жауап кодын және аудит жазбасын оқыңыз. Қайталанатын аутентификация қателері IP мекенжайын уақытша бұғаттайды.

Ауыстыру үшін әкімші жаңа кілт жасап, клиентті сақтайды: бұрынғы кілт жұмысын тоқтатады. Рөл рұқсат етсе, иелері «API → Менің API кілттерім» бөлімінде өз кілттерін қарап, жаңарта алады; өздігінен ауыстыру бірден күшіне енеді. Алмастырғаннан кейін ping және бір рұқсат етілген сценарийді тексеріп, ескі құпияны сыртқы жүйеден жойыңыз.

Тарихқа басқарылатын қатынау үшін мынаны пайдаланыңыз: GET /api/v1/flows/{flow}/runs. Аяқталған іске қосудың нәтижелер тізімі мынада қолжетімді: /api/v1/flows/{flow}/results?run=latest; нақты кесте — /api/v1/flows/{flow}/results/{block}?format=json&offset=0&limit=100. Идентификаторларды басқа мысалдан емес, жауаптан таңдаңыз. Бір нәтиженің бірнеше кестесін оқығанда нақты іске қосуды бекітіңіз: жаңа орындалудан кейін latest өзгеруі мүмкін. Бұл бағыттарға ағынның «Оқу» құқығы қажет және әр мекенжай мен бетке жеке қолтаңба керек.