17. Integracijos API ir API raktai

Integracijos API skirta tam, kad jūsų pačių programa, skaičiuoklė ar scenarijus automatiškai nuskaitytų jūsų projektų duomenis: projektų sąrašą, kabelių ir medžiagų žiniaraščius, skirstomųjų skydų grandinių lentelę ir gnybtų sąrašą, kiekių suvestinę ir projekto paketo sudarymą. API tik skaito: brėžinio ir projekto nekeičia.

Kas gali gauti API raktą

API raktą kiekvienai paskyrai įjungia operatorius. Jei jūsų paskyrai suteiktas leidimas, puslapyje Profilis atsiranda kortelė API raktai; be leidimo kortelė nematoma. Paskyra vienu metu gali turėti ne daugiau kaip 5 aktyvius raktus.

Raktas mato tuos pačius projektus kaip ir jūs: jūsų pačių ir, paprašius, tuos, kuriais su jumis pasidalyta. Bendrinamo projekto žiniaraščiai ir suvestinė pateikiami tik tada, jei dalijimasis leidžia ir eksportuoti.

Rakto sukūrimas

Puslapio Profilis kortelėje API raktai spustelėkite mygtuką Naujas raktas.
Raktui suteikite pavadinimą (pavyzdžiui, jį naudosiančios programos pavadinimą).
Pasirinkite apimtį: Skaityti projektus suteikia projektų sąrašą ir projektų duomenis, Skaityti dokumentus suteikia žiniaraščius, suvestinę ir projekto paketą. Nurodykite tik tai, ko programai tikrai reikia.
Pasirinkite galiojimo laiką: 30, 90 arba 365 dienos. Pasibaigusio galiojimo raktas nebeveikia; vietoj jo sukuriate naują.
Įveskite dabartinį slaptažodį (paskyrai be slaptažodžio reikia šviežio prisijungimo). Pirmam raktui sutikite su API naudojimo sąlygomis.

Sukūrus raktas rodomas tik vieną kartą: nukopijuokite jį ir laikykite saugioje vietoje. Vėliau sąraše matomas tik jo priešdėlis (avk_…), sukūrimo ir galiojimo pabaigos datos, paskutinis naudojimas ir iškvietimų skaičius. Apie naują raktą taip pat siunčiame pranešimą el. paštu (be paties rakto).

Rakto atšaukimas

Kortelėje prie rakto esantis mygtukas Atšaukti raktą nedelsiant padaro nebenaudojamą; šio veiksmo atšaukti negalima. Atšaukite raktą, kai jo nebenaudojate, kai nutraukiate jį naudojusią programą arba įtariate, kad jis nutekėjo.

Saugumo patarimai

Su raktu elkitės kaip su slaptažodžiu: kas jį žino, nurodytos apimties ribose gali skaityti jūsų projektus.
Laikykite jį paslapčių saugykloje (slaptažodžių tvarkyklėje, serverio aplinkos kintamajame ar CI slaptame kintamajame), o ne pradiniame kode: jis neturi patekti į git saugyklą, bendrinamą skaičiuoklę ar el. laišką.
Nenaudokite jo naršyklėje vykdomame kode (svetainėje, naršyklės plėtinyje): ten bet kas gali jį perskaityti. Rakto vieta yra serveryje, scenarijuje ar kompiuterio programoje.
Kiekviena programa turėtų turėti savo raktą su kuo siauresne apimtimi ir trumpu galiojimu; taip vieno rakto atšaukimas nesustabdo nieko kito.

Naudojimas iš programos

Užklausos antraštėje raktas siunčiamas kaip Bearer prieigos raktas: Authorization: Bearer avk_…. Galiniai taškai yra po /api/v1/ (pavyzdžiui, GET /api/v1/projects), atsakymas yra JSON. Tikslus aprašas OpenAPI formatu pasiekiamas adresu /api/v1/openapi.json; daugelis kūrimo įrankių gali jį importuoti.

Iškvietimų skaičius ribojamas pagal raktą ir pagal paskyrą (pagal numatytuosius nustatymus 60 per minutę ir 10 000 per dieną); viršijus serveris atsako 429, tad šiek tiek palaukite. Prisijungimas prie svetainės (slapukas) API neatveria, o raktas neprijungia prie žiniatinklio sąsajos.