Cloud Security (CSPM+) API гэж юу вэ, хэрхэн ашиглах вэ?

Танилцуулга

Bitdefender-ийн RESTful (REST) API нь хөгжүүлэгчдэд бизнесийн ажлын урсгалыг автоматжуулах боломж олгоно. REST API нь нөөц болон өгөгдлийг авах, өөрчлөхдөө командуудыг ашигладаг. Нөөцийн тухайн мөчийн төлөвийг нөөцийн дүрслэл (resource representation) гэнэ.

API дуудлагууд нь JSON агуулгатай GET HTTP эсвэл POST HTTP хүсэлт хэлбэрээр хийгдэнэ.

REST API нь RFC 2616 протоколд тодорхойлсон одоо байгаа HTTP аргачлалуудыг ашигладаг. Cloud Security-д REST API-ийн хоёр төрөл байдаг:

• GET - өгөгдөл болон нөөцийг авахад ашиглана.

GET нь тодорхой эх сурвалжаас мэдээлэл хүсэхэд хэрэглэдэг HyperText Transfer Protocol (HTTP)-ийн арга юм. Мөн бүлгээс гарган авсан тодорхой хувьсагчийг авахад ашигладаг. HTTP POST нь хөтчөөс серверийн мессежийн системд мэдээлэл оруулахыг хүсдэг. HyperText Markup Language (HTML)-ийн бүтцүүд POST эсвэл GET аргаар ирдэг. Аль аргыг хэрэглэх нь маягтын өгөгдлийг серверт хэрхэн толилуулахыг тодорхойлно.

• POST - нөөц үүсгэхэд ашиглана.

Энэ арга нь өгөгдлийг боловсруулагч скриптэд тусдаа мессеж болгон багцалж илгээх боломж олгоно. Иймээс POST аргаар илгээсэн өгөгдөл URL-д харагдахгүй, учир нь параметрүүд URI-тай хамт илгээгддэггүй.

HTTP POST-ийн бүтэц нь HTTP толгой хэсэг (headers), хоосон мөр, дараа нь хүсэлтийн агуулгаас (request body) бүрдэнэ. POST хүсэлтийг вэб маягт илгээх эсвэл файл байршуулахад ашиглаж болно. Гэхдээ хүлээн авагч програм ашиглаж буй форматтай нийцэж байгаа эсэхийг заавал шалгах хэрэгтэй. Content-Type толгой нь POST хүсэлтийн агуулгын төрлийг заана.

API дуудлага бүр нэг endpoint-д хандаж, олон параметр дамжуулдаг. Параметр хоёр төрөлтэй:

• required (заавал) - дуудаж буй аргад ЗААВАЛ дамжуулах ёстой.
• optional (заавал биш) - өгөгдмөл утгатай бөгөөд параметрийн жагсаалтаас орхиж болно. Заавал биш параметр бүрийг жагсаалт дахь байрлалаас үл хамааран алгасаж болно.

Жишээ:

GET /setting/scans/22f5ae90-f3da-4f57-9d89-0f860e******

API хүсэлтүүд

API дуудлагууд нь түүхий JSON мессежийг агуулга болгосон HTTP хүсэлт хэлбэрээр хийгдэнэ. GET болон POST endpoint хүсэлт хоёулаа байдаг.

Бүтээгдэхүүний тодорхой хэсэг, функцүүдэд зориулсан олон endpoint байдаг.

Бүх API-ийн үндсэн URL (base URL) таны консолоос хамаарч өөр өөр байна:

• Base URL 1:

```
https://api.e.cs.gravityzone.bitdefender.com/v1/
```

• Base URL 2:

```
https://api.u.cs.gravityzone.bitdefender.com/v1
```

• Base URL 3:

```
https://api.a.cs.gravityzone.bitdefender.com/v1
```

API-ийн бүтэн URL-ийг дараах алхмаар гаргана:

1. 1Хөтчийн шинэ таб нээж, Cloud Security консолдоо нэвтэрнэ.

2. 2URL-ийн https://api-ийн дараах хэсгээс gravityzone.bitdefender.com хүртэлх хэсгийг хуулна.

3. 3Үүнийг доорх загварт буулгана:

```
https://api..*.gravityzone.bitdefender.com/v1
```

API-ийн дэлгэрэнгүй мэдээллийг CSPM болон Settings хуудаснаас үзнэ үү.

Cloud Security консол руу хийх API дуудлагууд нь энд тайлбарласан HTTP Basic Authentication механизмаар HTTP протоколын түвшинд баталгаажна.

API түлхүүрийг хүсэлтийн толгойд, үсгийн том жижгийг ялгадаг x-api-key нэрээр оруулах ёстой:

x-api-key: API_KEY_VALUE

Мөн HTTP хүсэлт бүрт Content-Type толгойг application/json гэж тохируулсан байх шаардлагатай.

API нь нэг API түлхүүрт өдөрт 5000 хүсэлт эсвэл секундэд 50 хүсэлтээр хязгаарлагдана.

Энэ хязгаарыг хэтрүүлбэл дараагийн хүсэлтүүд татгалзагдаж, 429 HTTP статусын код буцаана. Мөн шинэ хүсэлт илгээх хүртэл үлдсэн секундийг заасан Retry-After толгойг хамт буцаана.

API түлхүүрүүд

API түлхүүр нь Cloud Security консолын Integration хуудсанд үүсгэгддэг өвөрмөц түлхүүр юм. API түлхүүр бүр програмд нэг буюу хэд хэдэн API-ийн аргуудыг дуудах эрх олгоно. Зөвшөөрөгдөх API-уудыг түлхүүр үүсгэх үед сонгоно.

API түлхүүр үүсгэх алхам:

1. 1Администраторын эрхтэй бүртгэлээр https://gravityzone.bitdefender.com/ руу нэвтэрнэ.

2. 2Cloud Security хуудсанд орж, Open Console товчийг дарна.

Хөтчийн шинэ таб нээгдэж, та Cloud Security консолд нэвтэрсэн байна.

3. 3Хуудасны баруун дээд булан дахь Settings (Тохиргоо) товчийг дараад Integrations-ийг сонгоно.

Integrations хуудас нээгдэнэ.

4. 4API Integration хэсгийн API Token-ий хажууд байгаа Create товчийг дарна.

> Тэмдэглэл: Хэрэв өмнө нь үүсгэсэн API түлхүүр байгаа бол товчны нэр View API tokens болно.

API Token самбар харагдана.

5. 5Самбарын баруун дээд буланд байгаа Create new API token товчийг дарна.

Самбарт нэмэлт мэдээлэл гарч ирнэ.

6. 6Түлхүүрийг дараа таних зорилгоор түүний зориулалтыг илтгэх Alias (нэр) бичээд Generate a new API token товчийг дарна.

Шинэ API түлхүүр үүсэж харагдана.

7. 7Токенийг аюулгүй газар хуулж хадгална.

> Чухал: Энэ самбарыг хаасны дараа Cloud Security консолоос түлхүүрийг дахин харах боломжгүй.

8. 8Done товчийг дарна.

Шинэ түлхүүр API token самбарт нууцлагдсан хэлбэрээр, Alias-ийн хамт нэмэгдэнэ. Үүсгэсэн огноо нь Integrations хуудасны Integration date баганад харагдана.

Cloud Security консол нь өмнө үүсгэсэн API түлхүүр хэрэггүй болсон үед тэдгээрийг идэвхгүй болгох боломжийг мөн олгоно:

1. 1Integrations хуудас руу орно.

2. 2API Integration хэсгийн API Token-ий хажууд байгаа View API tokens товчийг дарна.

3. 3Идэвхгүй болгох түлхүүрийнхээ Deactivate товчийг дарна.

Баталгаажуулах цонх гарч ирнэ.

4. 4Хүсэлтээ баталгаажуулахын тулд Deactivate-ийг сонгоно.

> Анхааруулга: Та эдгээр түлхүүрийг цаашид ашиглах боломжгүй болж, тэдгээрийг ашигласан гуравдагч талын програмуудтай холболт тасарна.

Статусууд

Хүсэлт амжилтгүй болсон үед дараах алдаанууд буцна:

• 200 — Ok (Амжилттай)
• 400 — Invalid query parameters. (Хүсэлтийн параметр буруу)
• 401 — API key not granted with the right permissions. (API түлхүүрт шаардлагатай эрх олгогдоогүй)
• 403 — Invalid API Key. (API түлхүүр буруу)
• 404 — Wrong resource path. (Нөөцийн зам буруу)
• 405 — Method not allowed. (Арга зөвшөөрөгдөөгүй)
• 429 — Throttling limits reached. (Хүсэлтийн хязгаарт хүрсэн)
• 500 — Internal Server Error. (Серверийн дотоод алдаа)