REST API icmalı

REST API konsolun arxasındakı HTTP API-dir: konsol öz sorğularını ona göndərir. Onu bearer giriş məlumatı ilə çağırırsınız, JSON göndərib qəbul edirsiniz və resursların çoxuna aid olduqları layihə (project) vasitəsilə müraciət edirsiniz.

Əsas URLKeçidi kopyalayın

API konsolun hostunda deyil, öz hostunda (API hostu) /api/v1 altında təqdim olunur:

https://<api-host>/api/v1

• <api-host>: API-nin host adı. Bu, konsolun hostu deyil.

Bu sənədlərdəki və API istinadı səhifəsindəki hər yol bu əsas URL-ə nisbətəndir. Virtual maşın (instance) yaratma ustadının son addımındakı REST equivalent bölməsi eyni yol və gövdə ilə curl əmridir. O, konsolun hostuna göndərilir: API-ni öz kodunuzdan çağırmaq üçün API hostundan istifadə edin.

İnteraktiv API bələdçisiKeçidi kopyalayın

API hostu API istinadını həm də brauzerinizdən sorğu göndərə biləcəyiniz interaktiv səhifə kimi təqdim edir:

https://<api-host>/docs

Authorize düyməsini seçin, API tokeni və ya xidmət hesabı açarı daxil edin, sonra əməliyyatda Try it out düyməsindən istifadə edin. Sorğular sizin etimadnamənizlə API hostuna gedir və real resurslarınız üzərində işləyir; buna görə oxuma əməliyyatları ilə və ya test üçün istifadə etdiyiniz layihə ilə başlayın. Səhifə etimadnaməni yalnız onu yenidən yükləyənə və ya bağlayana qədər saxlayır. Səhifənin əsaslandığı OpenAPI sənədi https://<api-host>/openapi.json ünvanındadır; ondan müştəri yaratmaq və ya API-ni API alətinə idxal etmək üçün istifadə edin.

Bu saytdakı API istinadı eyni əməliyyatları təsvir edir və sorğu göndərmir.

MiqyaslarKeçidi kopyalayın

Resursların çoxu layihəyə aiddir və onların yolları /scopes/ ilə, ardınca isə layihənin ID-si ilə başlayır:

/scopes/<project-id>/compute/instances

• <project-id>: resursların aid olduğu layihənin ID-si.

Layihə ID-sindən sonrakı seqment xidməti bildirir, məsələn, compute, storage və ya network. Bir neçə yol layihəyə aid deyil, məsələn, /operations/<operation-id>. Yolun tam quruluşu və layihənin ID-sini necə tapmaq barədə Miqyaslar, URL-lər və sorğu formatı səhifəsinə baxın.

AutentifikasiyaKeçidi kopyalayın

Hər sorğu Authorization başlığında giriş məlumatı daşıyır: pc_live_ ilə başlayan API tokeni (API token) və ya sak_live_ ilə başlayan xidmət hesabının (service account) açarı. API şlüzü sorğu xidmətə çatmazdan əvvəl hər sorğuda giriş məlumatını, layihənin resursları üçün isə həmin layihəyə girişinizi yoxlayır. Ətraflı məlumat üçün API tokenləri ilə autentifikasiyadan keçin səhifəsinə baxın.

Sinxron və asinxron sorğularKeçidi kopyalayın

Oxuma sorğuları nəticə ilə 200 OK qaytarır. Yazma sorğuları iki yoldan biri ilə cavab verir:

• Sinxron. Cavab gəldikdə dəyişiklik artıq tamamlanmış olur: nəticə ilə 200 OK və ya 201 Created, yaxud 204 No Content.
• Asinxron. Platforma sorğunu qəbul edir və işi sonra buludda icra edir. Cavab 202 Accepted olur. Məsələn, virtual maşının və ya diskin (volume) yaradılması, virtual maşının silinməsi, həmçinin virtual maşının başladılması və ya dayandırılması belə işləyir.

API istinadı hər əməliyyatın uğur statusunu göstərir.

202 Accepted cavabının gövdəsi iki növdən biri olur:

202 Accepted cavabındakı əməliyyat artıq SUCCEEDED vəziyyətindədirsə, iş tamamlanıb. Ödəniş üzrə yazma sorğuları, məsələn, büdcənin (budget) və ya öhdəliyin (commitment) yaradılması, belə cavab verir və onların əməliyyatlarını sonra oxumaq mümkün deyil.

Əməliyyat bir asinxron sorğunu izləyir. Onu GET /operations/<operation-id> ilə oxuyun:

{
  "id": "3f2b8c1e9d4a4f6b8e2c7a1d5b9e0f42",
  "action": "compute.instance.stop",
  "state": "RUNNING",
  "resourceKind": "instance",
  "resourceId": "9c1d6e2a7b3f4c8d9e0a1b2c3d4e5f60",
  "resourceName": "web-01",
  "createdAt": "2026-10-08T09:30:00Z",
  "startedAt": "2026-10-08T09:30:01Z",
  "updatedAt": "2026-10-08T09:30:01Z"
}

SUCCEEDED, FAILED və CANCELLED son vəziyyətlərdir. Başa çatmamış əməliyyatı ləğv etmək üçün Idempotency-Key başlığı ilə POST /operations/<operation-id>/actions/cancel göndərin. Artıq başa çatmış əməliyyatın ləğvi 409 Conflict qaytarır.

Əməliyyatı yalnız onun resursunu layihəsində oxuya bildiyiniz halda oxuya bilərsiniz; əks halda API 404 Not Found cavabını qaytarır. Onu ləğv etmək üçün həmin resursu idarə etməyə icazəniz (permission) olmalıdır.

Cavablardakı vaxt göstəriciləri nümunədə olduğu kimi UTC üzrə ISO 8601 sətirləridir.

İdempotent yazma sorğularıKeçidi kopyalayın

Hər yazma sorğusu ilə Idempotency-Key başlığı göndərin. Bağlantı kəsilərsə və sorğunun çatıb-çatmadığını bilmirsinizsə, onu eyni açarla yenidən göndərin: platforma dəyişikliyi ikinci dəfə tətbiq etmək əvəzinə ilk sorğunun nəticəsini qaytarır. Bir neçə əməliyyat açarı nəzərə almır. Qaydalar və istisnalar üçün İdempotent sorğular səhifəsinə baxın. API tokeni və ya xidmət hesabı açarı ilə resurs yaradan POST sorğusu açarsız rədd edilir: IDEMPOTENCY_KEY_REQUIRED kodu ilə 400 Bad Request. Digər yazma sorğularında açar məcburi deyil.

Paralel dəyişikliklərə nəzarətKeçidi kopyalayın

Bir çox resurs onları oxuduğunuz zaman ETag başlığı qaytarır. Oxuduğunuz versiyanı dəyişdiyinizə əmin olmaq üçün bu dəyəri yeniləmə sorğusu ilə If-Match başlığında göndərin. Resurs bu arada dəyişibsə, yeniləmə 412 Precondition Failed qaytarır: resursu yenidən oxuyun və yeniləməni təkrarlayın.

curl -X PATCH "https://<api-host>/api/v1/scopes/<project-id>/compute/instances/<instance-id>" \
  -H "Authorization: Bearer $PC_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: <etag>' \
  -H "Content-Type: application/json" \
  -d '{"name": "web-02"}'

• <instance-id>: virtual maşının ID-si.
• <etag>: virtual maşını sonuncu dəfə oxuduğunuz zaman alınan ETag başlığının dəqiq dəyəri, məsələn, W/"3a7bd3e2360a3d29eea436fcfb7e44c735d117c4".
• PC_TOKEN: API tokeninizi saxlayan mühit dəyişəni.

Bu yeniləmələr If-Match tələb edir. Başlıq olmadan onlar da 412 Precondition Failed qaytarır:

• Virtual maşının, diskin, şəbəkənin (network), altşəbəkənin (subnet), marşrutlaşdırıcının (router), təhlükəsizlik qrupunun (security group), şəbəkə interfeysinin və ya load balancer-in yenilənməsi.
• Ehtiyat nüsxə planının (backup plan) yenilənməsi və ya silinməsi.

Altşəbəkə üçün onun şəbəkəsinin ETag dəyərini göndərin. Altşəbəkələrin öz ETag dəyəri yoxdur və altşəbəkənin yenilənməsi şəbəkənin yeni ETag dəyərini qaytarır.

Siyahılar və səhifələməKeçidi kopyalayın

Siyahı əməliyyatları elementləri data, səhifələmə vəziyyətini isə meta daxilində qaytarır. Ətraflı məlumat üçün Səhifələmə səhifəsinə baxın.

Xətalar və sorğu limitiKeçidi kopyalayın

API-nin xəta cavabları eyni JSON formasındadır: maşın tərəfindən oxunan code, message və təkrar cəhd uğurlu ola bildikdə "retryable": true. Sorğuları çox sürətlə göndərsəniz, API Retry-After başlığı ilə 429 Too Many Requests qaytarır. API tokeni və ya xidmət hesabı açarı ilə göndərilən sorğunun hər cavabı X-RateLimit-Limit, X-RateLimit-Remaining və X-RateLimit-Reset başlıqlarını daşıyır; X-RateLimit-Reset limitin sıfırlanmasına qalan saniyələrin sayıdır. Kodlar və onlarla necə davranmaq barədə Xətalar səhifəsinə baxın.

Sorğu ID-ləriKeçidi kopyalayın

Hər cavab X-Request-Id başlığı daşıyır. X-Request-Id başlığını özünüz göndərsəniz, API sizin dəyərinizdən istifadə edir; əks halda onu özü yaradır. Sorğu ilə bağlı problem bildirərkən bu ID-ni göstərin.

Versiyalaşdırma və dəyişikliklərKeçidi kopyalayın

API v1 daxilində yalnız geriyə uyğun şəkildə dəyişir. Uyğunluğu pozan dəyişiklik ən azı 6 ay əvvəl elan edilir və təsirlənən əməliyyatın cavabları Deprecation və Sunset başlıqlarını daşıyır. Qaydalar üçün API versiyalaşdırması və istifadədən çıxarılma, dəyişikliklər üçün isə API dəyişiklik jurnalı səhifəsinə baxın.

Əlaqəli tapşırıqlarKeçidi kopyalayın

• API tokenləri ilə autentifikasiyadan keçin
• Miqyaslar, URL-lər və sorğu formatı
• İdempotent sorğular
• API versiyalaşdırması və istifadədən çıxarılma
• API dəyişiklik jurnalı
• API istinadı