1. Жариялау түпкі нүктесін жасаңыз
«Ағын деректерін жариялау» бағытымен «REST API» жасаңыз. Атауды, API нұсқасын және идентификаторды енгізіңіз, мысалы: stock. Мекенжай мына түрде болады: GET /api/v1/data/stock — орнатуыңыздың префиксімен. JSON, JSON Lines, CSV немесе XML таңдаңыз. CSV бөлгішін баптаңыз; XML үшін баған атаулары жарамды элемент атаулары болуы керек.
Қорғалған түпкі нүктеге бөлек қосылым құпиясы қажет емес: тұтынушы өз API клиентін пайдаланады. Сақталған нәтижелер үшін деректердің ең үлкен жасын орнатыңыз. «API шектеулері» жауаптағы жол санын шектей алады; сұраудағы limit мәні шектен жоғары болса, рұқсат етілген мәнге дейін азаяды.
2. Ағындағы нәтижені қосыңыз
«API: деректерді қабылдау және жариялау» тобынан «API деректерін жариялау» блогын қосып, бос түпкі нүктені таңдаңыз. Оның кірісін кестесі ұсынылуы тиіс блокпен байланыстырыңыз. Бұл дайын түрлендіру нәтижесі немесе жазудан кейінгі қабылдаушы нәтижесі болуы мүмкін. Маршрутизатор үшін қажетті шығысты таңдаңыз.
Блок өз тармағын аяқтайды және шығыстары жоқ. Бір ағынға бір жариялау блогы рұқсат етіледі; түпкі нүкте бір жарияланған ағынға тиесілі. Бос емес түпкі нүктені қайта пайдалану мына қатемен қабылданбайды: API_POINT_TAKEN. Ағынды сақтап, жариялаңыз. Жарияланғанға дейін түпкі нүкте мынаны қайтарады: 409 API_ENDPOINT_NOT_READY; сақталған нәтижелер режимінде алғашқы іске қосу да қажет.
3. Өзектілік режимін таңдаңыз
«Соңғы іске қосудың сақталған нәтижелері» соңғы аяқталған Production іске қосуының кестесін қайтарады: сәтті немесе ішінара. GET ағынды орындамайды. Жаңартуды кесте не басқа рұқсат етілген механизм арқылы ұйымдастырыңыз. Бапталған шектен ескі деректер мына қатеге әкеледі: 409 API_DATA_STALE; нөл жасын тексеруді өшіреді.
«Әр сұрау үшін ағынды іске қосу» Production нұсқасын интерактивті қатысусыз орындайды. Күтуді 1–120 секунд, нәтижені қайта пайдалануды 0–3600 секунд етіп орнатыңыз. Бірдей іске қосу параметрлері аяқталған нәтижені қайта пайдалана алады; қатар келген бірдей сұраулар сол іске қосуды күтеді. Кілт иесіне орындау құқығы, клиентке «Оқу» қажет. Бұл режимде сақталған дерек жасының шегі қолданылмайды.
4. API параметрлерін қосыңыз
Блок қасиеттерінде «Параметр қосу» түймесін басыңыз. Атау латын әрпінен басталып, 40 таңбаға дейінгі әріптерден, цифрлардан немесе астын сызудан тұрады; offset, limit және run — сақталған атаулар. Интегратор үшін сипаттама қосыңыз. Параметр жолдарды өріс бойынша сүзе алады немесе ағынның іске қосу параметріне мән бере алады; екіншісі тек сұрау бойынша орындауда қолжетімді.
Түрін — мәтін, сан немесе күн — міндеттілігін, рұқсат етілген мәндерді не шектерді орнатыңыз. Мысалы, warehouse Warehouse өрісін сүзеді, ал date күнді сүзеді. Мынаны қайталау: warehouse=KYIV&warehouse=LVIV бірнеше мәнді таңдайды; date_from және date_to шеттері кіретін ауқымды белгілейді. Әртүрлі параметрлер бірге қолданылады. Қабылдаудан айырмашылығы, мұнда p. префиксі қолдау таппайды.
5. Бір нәтиженің беттерін оқыңыз
Төмендегі сұрау warehouse параметрі бапталған деп есептейді. Кілт және HMAC тақырыптарын мына ережелерге сай қосыңыз: клиент ережелері. Жауаптар мынаны қамтиды: X-Total-Rows, X-Run-Id, X-Run-Finished және ETag. Келесі бет үшін мына сілтемемен өтіңіз: Link немесе X-Next-Offset — параметрлер мен іске қосу идентификаторын сақтап.
GET /api/v1/data/stock?warehouse=KYIV&offset=0&limit=100
Authorization: Bearer API_KEY
X-UBC-Timestamp: UNIX_SECONDS
X-UBC-Signature: v1=HMAC_HEXЖаңа іске қосу уақытында аяқталмаса, 202 API_RUN_PENDING мынаны қайтарады: next, Location, Retry-After және run.id. Күтіп, next сұрауын жіберіңіз: онда run=... бар және ол басқа іске қосуды бастамайды. Өзгермеген ETag мәнімен мынаны жіберіңіз: If-None-Match — мына жауапты алу үшін: 304.
6. Қатынау, қателер және қабылдау тексеруі
Ішкі деректер үшін түпкі нүктені қорғалған күйде ұстаңыз. «Ашық түпкі нүкте — кілтсіз және қолтаңбасыз қатынау» растаудан кейін оны кез келген адамға ашады; бөлек IP шегі мен жалпы API шегі бәрібір қолданылады. Техникалық құжаттама мен басқа бағыттар автоматты ашылмайды.
Жарамды және жетіспейтін параметрлерді, бірнеше бетті, ескірген деректерді және құқығы жоқ пайдаланушыны сынаңыз. 400 API_PARAMETER_REQUIRED жетіспейтін параметрді білдіреді; API_PARAMETER_INVALID— жарамсыз мәнді; API_QUERY_UNKNOWN— белгісіз атауды. Жетіспейтін өріс мына қатеге әкеледі: 409 API_PARAMETER_FIELD; сәтсіз іске қосу — 502 API_RUN_FAILED. Тек HTTP 200 емес, сүзілген санды, нақты кілттерді және run.id мәнін тексеріңіз.
Орындау режимінде ашық түпкі нүкте ағынды жариялаушы пайдаланушы құқықтарымен орындайды; қатынауды қоспас бұрын оларды тексеріңіз. Мына анықтамада: «API деректерін жариялау» блогы блок баптаулары келтірілген.