KB Management API User Guide

This document provides a guide on how to use the API to manage the Knowledge Base (KB) system from external scripts (such as giipAgentWin).

🔌 Go to Knowledge Base Management →

1. Overview

By calling the KB API (giipKb), you can store and retrieve troubleshooting know-how, configuration information, etc., for a specific server (lssn) or database (mdb_id).

2. Basic Information

• Endpoint: https://giipfaw.azurewebsites.net/api/giipKb
• Authentication: Session tokens (AK/SK) must be passed through the x-api-key header.

3. Function Introduction (Endpoints)

3.1 KB Registration (POST)

Registers a new knowledge document.

Payload (JSON):

{
  "csn": 100,
  "refType": "LSSN", 
  "lssn": 1234,
  "title": "Server Kernel Tuning Guide",
  "content": "# Guide\nHow to modify kernel parameters...",
  "tags": "kernel,tuning,linux"
}

• refType: Choose from LSSN (Server), MDB (DB), or GENERAL.

3.2 KB Update (PUT)

Modifies an existing knowledge document.

Payload (JSON):

{
  "kbSn": 42,
  "title": "Updated Title",
  "content": "Updated content...",
  "tags": "linux,updated"
}

3.3 KB Inquiry (GET)

Retrieves a list of KB documents or detailed information that matches the filter conditions.

Query Parameters:

• kbSn: Use when inquiring about a specific document.
• lssn: Inquire about knowledge related to a specific server.
• mdb_id: Inquire about knowledge related to a specific DB.
• searchKeyword: Search keyword.

3.4 KB Deletion (DELETE)

Deletes a knowledge document.

Query Parameters:

• kbSn: Number of the document to be deleted.

---

4. How to Use SK-based APIs (Recommended for giipAgent)

For persistent programs like giipAgent or automation scripts, it is recommended to use a Secret Key (SK) that does not have a session expiration. SK-based calls are performed through the integrated API endpoint (giipApiSk3).

• Endpoint: https://giipfaw.azurewebsites.net/api/giipApiSk3
• Method: POST (form-urlencoded)

4.1 Key Parameters

• sk: Your issued Secret Key.
• text: The command to execute (one of KbCreate, KbUpdate, KbDelete, KbGet, KbList).
• jsondata: Detailed data to be passed to the API (JSON string).

4.2 Call Example (PowerShell)

$sk = "YOUR_SECRET_KEY"
$url = "https://giipfaw.azurewebsites.net/api/giipApiSk3"

# KB Registration Example
$body = @{
    sk = $sk
    text = "KbCreate jsondata"
    jsondata = (@{
        csn = 100
        refType = "LSSN"
        lssn = 1234
        title = "Knowledge Automatically Registered by Agent"
        content = "This content has been automatically analyzed from the agent."
        tags = "agent,auto"
    } | ConvertTo-Json -Compress)
}

$response = Invoke-RestMethod -Uri $url -Method Post -Body $body
Write-Host "KB Registered. kbSn: $($response.data[0].kbSn)"

---

5. giipAgentWin Automation Example (AK-based)

This is an example of automatically registering completed task logs as KBs in the giipAgentWin script (when the login session is valid).

$ak = "YOUR_SESSION_AK"
$url = "https://giipfaw.azurewebsites.net/api/giipKb"

$body = @{
    title = "Automation Analysis Result - $(Get-Date -Format 'yyyyMMdd')"
    content = "# Analysis Result`nEnvironment check has been completed."
    refType = "LSSN"
    lssn = 1201
    csn = 0
    tags = "auto,diag"
} | ConvertTo-Json -Compress

$headers = @{
    "x-api-key" = $ak
    "Content-Type" = "application/json"
}

$response = Invoke-RestMethod -Uri $url -Method Post -Headers $headers -Body $body
Write-Host "KB Registered. kbSn: $($response.kbSn)"

[!TIP] You can immediately check the content registered through this API on the server/DB detail page of the giipv3 frontend.

---

Troubleshooting

Symptom	Cause	Solution
401 Unauthorized response	The x-api-key header lacks a valid AK/SK token, or the session has expired	Provide a valid token in the header, or switch to the session-less SK-based giipApiSk3 call
Command not executed on SK call	The text field is not in the KbCreate jsondata form	Set text to the exact command (KbCreate/KbUpdate/KbDelete/KbGet/KbList) plus the jsondata keyword
Data missing on create/update	refType is not one of LSSN/MDB/GENERAL, or kbSn is omitted	Use only one of the allowed refType values, and supply a valid kbSn for PUT/DELETE
jsondata parsing error	Newlines or quotes inside content are not escaped	Serialize to a JSON string (e.g., ConvertTo-Json -Compress) before sending