17. ინტეგრაციის API და API გასაღებები

ინტეგრაციის API საშუალებას გაძლევთ, თქვენმა პროგრამამ, ცხრილმა ან სკრიპტმა ავტომატურად წაიკითხოს პროექტის მონაცემები: პროექტების სია, კაბელებისა და მასალების უწყისები, გამანაწილებელი ფარების წრედების ცხრილი და კლემების სია, რაოდენობების ამონაწერი და ნახაზების პაკეტის შედგენა. API მხოლოდ კითხულობს: ნახაზს ან პროექტს არასდროს ცვლის.

ვის შეუძლია API-გასაღების მიღება

API-ზე წვდომას ანგარიშის მიხედვით ოპერატორი რთავს. როცა თქვენს ანგარიშს წვდომა მიეცემა, პროფილი გვერდზე გამოჩნდება API გასაღებები ბარათი; წვდომის გარეშე ბარათი დამალულია. ერთ ანგარიშს ერთდროულად მაქსიმუმ 5 აქტიური გასაღები შეიძლება ჰქონდეს.

გასაღები ხედავს იმავე პროექტებს, რასაც თქვენ: თქვენსას და მოთხოვნით იმათაც, რომლებიც თქვენთან გაზიარდა. გაზიარებული პროექტის უწყისები და ამონაწერი მხოლოდ მაშინ გაიცემა, თუ გაზიარება ექსპორტსაც ნებას რთავს.

გასაღების შექმნა

1. პროფილი გვერდის API გასაღებები ბარათზე დააჭირეთ ახალი გასაღები ღილაკს.
2. მიანიჭეთ გასაღებს სახელი (მაგალითად, იმ პროგრამის სახელი, რომელიც მას გამოიყენებს).
3. აირჩიეთ მოქმედების არეალი: პროექტების წაკითხვა იძლევა პროექტების სიას და პროექტის მონაცემებს, დოკუმენტების წაკითხვა — უწყისებს, ამონაწერს და ნახაზების პაკეტს. აირჩიეთ მხოლოდ ის, რაც პროგრამას ნამდვილად სჭირდება.
4. აირჩიეთ ვადა: 30, 90 ან 365 დღე. ვადაგასული გასაღები აღარ მუშაობს; ახალი შექმენით მის ნაცვლად.
5. შეიყვანეთ თქვენი მიმდინარე პაროლი (უპაროლო ანგარიშისთვის საჭიროა ახალი შესვლა). პირველი გასაღებისთვის დაეთანხმეთ 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-ს არ ხსნის, ხოლო გასაღები ვებინტერფეისზე არ შეგიყვანთ.