Public API (нийтийн API)

Танилцуулга

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

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

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

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

API хүсэлтүүд

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

Тайлбар

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

Control Center нь бүтээгдэхүүний өөр өөр хэсгийг хариуцсан олон API-г ашиглалтад гаргадаг. API бүр нь тухайн хэсэгтэй холбоотой method-уудын багцыг агуулна. Бүх API-ийн үндсэн (base) URL нь GravityZone суулгасан машины hostname, домэйн эсвэл IP хаяг юм: https://YOUR-HOSTNAME/api/v1.0/jsonrpc/. API-ийн бүтэн URL-ийг авахын тулд үндсэн URL-ийн араас API-ийн нэрийг залгана.

Анхаар

• Хандах URL (API endpoint гэж нэрлэдэг) аюулгүй эсэхийг шалга. Аюулгүй URL үргэлж https:// протоколоор эхэлнэ.
• API-ийг автоматжуулахад програм ашиглаж байгаа бол тэр програм SSL/TLS гэрчилгээг баталгаажуулдаг эсэхийг шалга. Энэ нь дундаас халдах (man-in-the-middle) төрлийн халдлагаас сэргийлнэ.
• Орчин үеийн TLS протоколыг дэмждэг шинэчлэгдсэн сан (library) эсвэл framework ашигла.

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

• Accounts, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/accounts

• General, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/general

• Maintenance windows, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/maintenanceWindows

• Network, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/network

• Packages, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/packages

• Policies, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/policies

• Quarantine, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/quarantine

• Reports, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/reports

• Sandbox, API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/sandbox

• Sandbox Portal, API URL:

https://SANDBOX-IP/api/v1

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

Тайлбар

Control Center одоогоор багц (batch) хүсэлт болон мэдэгдэл (notification)-ийг дэмжихгүй.

API түлхүүрүүд

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

Нэвтрэлт (Authentication)

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

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

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

• Нэвтрэлтийн method ба зайг угтвар болгон бичнэ. Манай тохиолдолд энэ нь үргэлж Basic байна.
• username:password хосолсон дарааллаас үүсгэсэн Base64 кодлогдсон мөр.

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

Жишээ нь API түлхүүр нь

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

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

Basic TjhLendjcVZVeEFJMVJvUGk1anlGSlBrUGxrRGw5dkY6 болно.

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

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

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

Алдааны бүрэн тайлбар нь алдааны мессежийн 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 төлөвийн кодыг алдааны төрлөөс хамааруулан тогтооно: