Public API (нийтийн API)-ийн танилцуулга

Танилцуулга

Bitdefender Control Center API нь хөгжүүлэгчдэд бизнесийн ажлын урсгалыг автоматжуулах боломжийг олгоно.

API нь JSON-RPC 2.0 протокол-оор ажилладаг.

Доор Control Center дэх компанийн нэрийг шинэчлэх API дуудлагын жишээг үзүүллээ:

    {
        "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7",
        "jsonrpc": "2.0",
        "method": "updateCompanyDetails",
        "params": {
            "name": "My Company Name"
        }
    }

Энэ дуудлагад дараах хариуг аппликейшн рүү буцаана:

    {
        "id":"91d6430d-bfd4-494f-8d4d-4947406d21a7",
        "jsonrpc":"2.0",
        "result": null
    }

API дуудлага бүр нэг method-ыг (аргыг) зорьж, түүнд параметрүүд дамжуулна.

Параметр хоёр төрөлтэй:

• required (заавал) - дуудаж буй method-д ҮРГЭЛЖ дамжуулах ЁСТОЙ.
• optional (сонголттой) - анхдагч утгатай бөгөөд параметрийн жагсаалтаас орхиж болно. Сонголттой параметр бүрийг жагсаалт дахь байрлалаас үл хамааран алгасаж болно.

API хүсэлтүүд

API дуудлагыг JSON-RPC мессежийг ачаалал (payload) болгосон HTTP хүсэлтээр гүйцэтгэнэ. API дуудлага бүрт HTTP POST method-ыг ЗААВАЛ хэрэглэнэ. Мөн HTTP хүсэлт бүрийн Content-Type толгойг application/json гэж тохируулах шаардлагатай.

Control Center нь продуктын тусдаа хэсгүүдэд чиглэсэн олон API-г нээдэг. API бүр тухайн хэсэгтэй холбоотой method-уудын багцыг агуулна.

Бүх API-ийн үндсэн URL нь: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/. API-ийн бүтэн URL-ийг үндсэн URL-д API-ийн нэрийг залгаж гаргана.

CONTROL_CENTER_APIs_ACCESS_URL нь Access URL талбарт харагдана. Энэ талбарыг олохын тулд консолын баруун дээд буланд байгаа хэрэглэгчийн дүрс (user icon)-ыг дараад My Account (Миний данс)-ыг сонгоно. Дараа нь Control Center API хэсэг рүү очно.

Одоогоор дараах API-ууд нээлттэй байна:

1. 1Accounts, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/accounts
```

2. 2Companies, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/companies
```

3. 3General, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/general
```

4. 4Incidents, API URL-ууд:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/incidents
```

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.1/jsonrpc/incidents
```

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.2/jsonrpc/incidents
```

5. 5Investigation, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/investigation
```

6. 6Integrations, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/integrations
```

7. 7Licensing, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/licensing
```

8. 8Maintenance windows, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/maintenanceWindows
```

9. 9Network, API URL-ууд:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/network
```

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.1/jsonrpc/network
```

10. 10Packages, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/packages
```

11. 11PHASR, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/phasr
```

12. 12Policies, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/policies
```

13. 13Push, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/push
```

14. 14Quarantine, API URL-ууд:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/quarantine
```

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.1/jsonrpc/quarantine
```

15. 15Reports, API URL:

```
CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/reports
```

JSON-RPC 2.0 агуулсан HTTP хүсэлтийг API URL бүр дээр гүйцэтгэж, нээлттэй функцыг ашиглаж болно.

API түлхүүрүүд

Хувийн API түлхүүрийг My account хуудсанд үүсгэж болно. Эдгээр түлхүүр таны Control Center дансанд холбогдоно. Дэлгэрэнгүйг Таны данс хуудаснаас үзнэ үү.

Service API түлхүүрийг Control Center-ийн үндсэн цэсийн Accounts > Service API keys хуудсанд үүсгэж болно. Эдгээр түлхүүр нь Control Center-ийн ямар ч хувийн данснаас хамаардаггүй бөгөөд тэдгээр дансанд хийсэн өөрчлөлтөд нөлөөлөгдөхгүй. Дэлгэрэнгүйг Service API keys хуудаснаас үзнэ үү.

Нэвтрэлт танилт (Authentication)

Хувийн API түлхүүрүүд

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

Клиент аппликейшн API-г дуудах бүртээ Authorization хүсэлтийн толгойг илгээх шаардлагатай.

Authorization толгой дараах хэсгүүдээс бүрдэнэ:

1. 1Угтвар болох authorization method болон зай; манай тохиолдолд энэ нь үргэлж Basic байна.

2. 2username:password дараалалыг нэгтгэж Base64-ээр кодолсон мөр.

Манай тохиолдолд API түлхүүрийг username, нууц үгийг хоосон мөр болгож тохируулна.

Жишээлбэл, API түлхүүр

N8KzwcqVUxAI1RoPi5jyFJPkPlkDl9vF бол Base64 кодчилолыг дараах мөр дээр гүйцэтгэнэ:

N8KzwcqVUxAI1RoPi5jyFJPkPlkDl9vF:. Энэ тохиолдолд authorization толгойд илгээх агуулга нь

Basic TjhLendjcVZVeEFJMVJvUGk1anlGSlBrUGxrRGw5dkY6 байна.

Service API түлхүүрүүд

Service API түлхүүр X-API-Key HTTP толгойгоор нэвтрэлт танилт хийнэ. Дэлгэрэнгүйг Public API хуудаснаас үзнэ үү.

POST /v1.0/jsonrpc/network HTTP/1.1
Host: <YOUR_GRAVITYZONE_ACCESS_URL>
Content-Type: application/json
X-API-Key: <your-service-api-key>

{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "getNetworkInventoryItems",
  "params": {
    "parentId": "root"
  }
}

GravityZone түлхүүрийг дараах дарааллаар боловсруулна:

1. 1X-API-Key толгойноос түлхүүрийн утгыг уншина.
2. 2Түлхүүрийг SHA-256-аар хэшлэнэ.
3. 3Хэшийг мэдээллийн санд хадгалсан бүртгэлтэй тулгана.
4. 4Хүчинтэй хугацааг шалгана. Хугацаа нь дууссан түлхүүрийг татгалзана.
5. 5Холбогдох service account-ыг ачаална.
6. 6Зөвшөөрөл болон зорилтод суурилсан хандалтыг мөрдүүлнэ.

Алдааны мэдээлэл

Хүссэн API method нь шаардлагатай үйлдлийг гүйцэтгэж чадахгүй бол Control Center алдаа буцаана.

Алдааны код болон алдааны мессежийг JSON-RPC 2.0 Specification-д заасны дагуу буцаана:

• Parse error — -32700; Parse error
• Invalid request — -32600; Invalid Request
• Method not found — -32601; Method not found
• Invalid params — -32602; Invalid params
• Server error — -32000; Server error
• Authorization error (API хүсэлтийг баталгаажуулж чадаагүй эсвэл дуудагчид эрх байхгүй үед буцаана. Хүчингүй/дутуу API түлхүүр, API түлхүүрийн хүрээ хангалтгүй, хэрэглэгчийн эрх дутуу, лицензийн хязгаарлалтыг хамарна.) — -32001; Authorization error
• Resource not found (хүссэн нөөц (incident, task, maintenance window гэх мэт) байхгүй эсвэл хандах боломжгүй үед буцаана. Багц хүсэлтэд аль ID-ууд олдоогүйг дэлгэрэнгүй мэдээлэлд жагсааж болно.) — -32002; Resource not found
• Too many requests (дуудагч хүсэлтийн хязгаараас хэтэрсэн үед бусад алдаа шиг 200 биш HTTP 429 статус кодтой буцаана. Retry-After хариуны толгой нь дахин оролдохоос өмнө хэдэн секунд хүлээхийг заана. Хязгаар нь API түлхүүр тутамд тогтоогдох бөгөөд method болон захиалгын түвшнөөс хамаарч өөр байж болно.) — -32003; Too many requests

Алдааны бүрэн тайлбар алдааны мессеж доторх data.details талбарт байна. Жишээнүүд:

• API түлхүүрийн хүрээнээс хэтэрсэн хүсэлтийн алдааны хариу:

```
{
"id": "abc123",
"jsonrpc": "2.0",
"error": {
"code": -32001,
"message": "Authorization error",
"data": {
"details": "API Key is not allowed to access the selected API: Incidents"
}
}
}
```

• Байхгүй эсвэл олдохгүй нөөцийг дурдсан хүсэлтийн алдааны хариу:

```
{
"id": "abc123",
"jsonrpc": "2.0",
"error": {
"code": -32002,
"message": "Resource not found",
"data": {
"details": "There is no incident with the specified ID"
}
}
}
```

• Хүсэлтийн хязгаараас хэтэрсэн үеийн алдааны хариу:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
"id": "abc123",
"jsonrpc": "2.0",
"error": {
"code": -32003,
"message": "Too many requests",
"data": {
"details": "Rate limit exceeded. Maximum 100 requests per 60 seconds allowed. Try again later."
}
}
}
```

HTTP статус кодыг алдааны төрлөөс хамааруулан тогтооно:

• `401` Unauthorized — Хүсэлтийн нэвтрэлт танилт амжилтгүй болсон (жишээ нь API түлхүүр буруу эсвэл байхгүй).
• `403` Forbidden — Хүсэлт хүссэн функцыг ашиглах эрхгүй (жишээ нь ашигласан API түлхүүрт тухайн API идэвхжээгүй).
• `405` Method Not Allowed — HTTP method нь POST биш.
• `429` Too Many Requests — Нэг API түлхүүрээс секундэд 10-аас олон хүсэлт илгээсэн.
• `200` HTTP статус код — Амжилттай хүсэлт, эсвэл серверийн алдаанаас болж бүтэлгүйтсэн хүсэлтэд (жишээ нь заавал дамжуулах параметр дутуу) буцаана.