Sk3 (High-fidelity Logging & Integrity) API Guide

This guide describes how to use giipApiSk3, a high-fidelity logging bridge API designed for agent transmission error detection and data integrity verification on the GIIP platform.

📋 Overview

giipApiSk3 is an enhanced endpoint that adds powerful logging and data parsing capabilities to the existing giipApi. It automatically records detailed logs of all exceptions and warnings during agent request processing into the tErrorLogs table, and provides features for automatically mapping complex JSON data to SQL parameters.

⚠️ Endpoint Positioning (Important)

giipApiSk3 is a debug / high-fidelity logging verification endpoint and uses Anonymous authentication at the Azure Function level. The standard production endpoint for agents is giipApiSk2. Do not permanently route production traffic to Sk3. Sk3 is a copy of Sk2's processing logic plus detailed logging, so if a request that works on Sk2 fails only on Sk3, that indicates a bug in Sk3's debug code (in that case never modify Sk2 — inspect Sk3 only).

📡 Endpoint Information

• URL: https://giipfaw.azurewebsites.net/api/giipApiSk3
• Authentication: While anonymous authentication is used at the Azure Function level, you must include a valid usertoken (AK) or sk (Secret Key) field in the request body for actual database operations.

🔐 Key Parameters

Field	Type	Description
text	String	Execution command string (e.g., LSVRList, KVSPut)
jsondata	String	JSON string containing complex parameters
token / sk	String	Access Key or Secret Key for authentication
user_id	String	Caller's user ID
lssn	String	Session or server identifier (if required)

🚀 Key Features

1. High-fidelity Logging

Automatically collects client IP, User-Agent, and Referer information for every API call. In case of errors, it records detailed logs including StackTrace into tErrorLogs.

2. Automatic jsondata Substitution

Automatically replaces keywords within the text parameter with corresponding values from jsondata.

• Example:
  • text: LSvrPut 'jsondata', 44
  • jsondata: {"lsUsage": "Web_Server"}
  • Actual Query: exec pApiLSvrPutbySk '...', N'Web_Server', 44

3. Automatic KVSPut Mapping

If the text contains the KVSPut command, it automatically extracts kType, kKey, kFactor, and kValue fields from jsondata to call the pApiKVSPutbySk procedure.

💻 Usage Examples

PowerShell Example

$apiUrl = "https://giipfaw.azurewebsites.net/api/giipApiSk3"
$body = @{
    text      = "KVSPut lssn, 1234, netstat"
    jsondata  = @{
        connections = @(
            @{ remote_ip = "10.0.0.10"; state = "ESTABLISHED" }
        )
    } | ConvertTo-Json -Compress
    usertoken = "YOUR_ACCESS_KEY"
}

$resp = Invoke-RestMethod -Uri $apiUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $body
$resp.data

cURL Example

curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk3" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "text=ErrorLogList 50" \
     --data-urlencode "usertoken=YOUR_ACCESS_KEY"

🔍 Response Structure

On success, it returns a JSON structure like the following:

{
  "data": [
    { ... result records ... }
  ],
  "debug": {
    "_debug_spName": "ErrorLogList",
    "_debug_executedQuery": "exec pApiErrorLogListbySk '...', 50"
  }
}

Troubleshooting

Symptom	Cause	Resolution
Every request returns HTTP 500	A syntax/compile error in the Sk3 debug function (Sk2 works fine)	Never modify Sk2; inspect only the giipApiSk3 function code and fix the syntax error.
RstVal 401 or an auth rejection occurs	The usertoken (AK) or sk field is missing from the request body	Include a valid usertoken/sk in the body, separate from the anonymous function auth.
jsondata values are not applied to the executed query	Mismatch between the substitution keyword in text and the jsondata field name	Ensure the 'jsondata' slot in text and the jsondata key (e.g., lsUsage) match exactly.
A KVSPut call is ignored or stored with empty values	Missing kType/kKey/kFactor/kValue fields in jsondata	Include all four fields so the pApiKVSPutbySk mapping completes.

---

Version: 1.0
Last Updated: 2026-04-10
Source File: giipv3/public/help/api-sk3.en.md

---

Related Documents:

• API Result Codes Guide (RstVal)