17. Интеграция API және API кілттері

Интеграция API өз бағдарламаңызға, кестеңізге немесе скриптіңізге жоба деректерін автоматты түрде оқуға мүмкіндік береді: жобалар тізімі, кабель және материал тізімдері, бөлу қалқандарының тізбек кестесі мен қысқыш тізімі, көлем есебі және сызба топтамасын құрастыру. API тек оқиды: сызбаны немесе жобаны ешқашан өзгертпейді.

API кілтін кім ала алады

API-ге қолжетімділікті оператор есептік жазба бойынша қосады. Есептік жазбаңызға рұқсат берілгеннен кейін Профиль бетінде API кілттері картасы пайда болады; рұқсатсыз бұл карта жасырын. Бір есептік жазбада бір уақытта ең көбі 5 белсенді кілт болуы мүмкін.

Кілт сізбен бірдей жобаларды көреді: өз жобаларыңызды және сұраныс бойынша сізбен бөлісілгендерді. Бөлісілген жобаның тізімдері мен есебі тек бөлісу экспортқа да рұқсат берсе ғана беріледі.

Кілт жасау

Профиль бетінің API кілттері картасында Жаңа кілт түймесін басыңыз.
Кілтке ат беріңіз (мысалы, оны қолданатын бағдарламаның аты).
Қолжетімділік аясы өрісін таңдаңыз: Жобаларды оқу жобалар тізімі мен жоба деректерін, Құжаттарды оқу тізімдерді, есепті және сызба топтамасын береді. Бағдарламаға шынымен қажетті нәрсені ғана таңдаңыз.
Жарамдылық мерзімі өрісін таңдаңыз: 30, 90 немесе 365 күн. Мерзімі өткен кілт жұмыс істемейді; орнына жаңасын жасаңыз.
Ағымдағы құпия сөзіңізді енгізіңіз (құпия сөзсіз есептік жазба үшін жаңа кіру қажет). Бірінші кілт үшін API пайдалану шарттарын қабылдаңыз.

Жасалғаннан кейін кілт бір рет қана көрсетіледі: оны көшіріп, қауіпсіз жерде сақтаңыз. Кейін тізімде тек оның префиксі (avk_…), жасалған және аяқталу күндері, соңғы пайдалану және шақырулар саны көрінеді. Жаңа кілт туралы электрондық пошта хабарландыруын да жібереміз (кілттің өзінсіз).

Кілтті қайтарып алу

Кілттің жанындағы Қайтарып алу түймесі оны дереу жарамсыз етеді; мұны болдырмау мүмкін емес. Кілтті енді пайдаланбасаңыз, оны қолданған бағдарламаны тоқтатсаңыз немесе сыртқа шықты деп күдіктенсеңіз, қайтарып алыңыз.

Қауіпсіздік кеңестері

Кілтке құпия сөзіңіздей қараңыз: оны білетін кез келген адам қамту аясында жобаларыңызды оқи алады.
Оны бастапқы кодта емес, құпиялар қоймасында (құпия сөз менеджері, сервердің орта айнымалысы немесе CI құпиясы) сақтаңыз: ешқашан git репозиторийіне, ортақ кестеге немесе электрондық поштаға салмаңыз.
Браузерде жұмыс істейтін кодта пайдаланбаңыз (веб-бет, браузер кеңейтімі): онда оны кез келген адам оқи алады. Кілттің орны серверде, скриптте немесе десктоп бағдарламада.
Әр бағдарламаға ең тар қамту аясымен және қысқа мерзіммен жеке кілт беріңіз, сонда бір кілтті қайтарып алу басқасын тоқтатпайды.

Бағдарламадан пайдалану

Кілт сұраныс тақырыбында Bearer токені ретінде жіберіледі: Authorization: Bearer avk_…. Эндпоинттер /api/v1/ астында орналасқан (мысалы, GET /api/v1/projects) және JSON түрінде жауап береді. OpenAPI пішіміндегі толық сипаттама /api/v1/openapi.json мекенжайында қолжетімді; көптеген әзірлеуші құралдары оны импорттай алады.

Шақырулар саны кілт және есептік жазба бойынша шектелген (әдепкіде минутына 60 және тәулігіне 10 000); асқанда сервер 429 жауабын береді, сәл күтіңіз. Веб-сайтқа кіру (cookie) API-ді ашпайды, ал кілт сізді веб-интерфейске кіргізбейді.