ClawHub

guanyuan data

Integrations

观远数据API工具 - 支持多种认证方式、Token自动管理、卡片数据获取和CSV导出

Install

openclaw skills install @jackeylee007/guanyuan-data

观远数据 API Skill

Description

This skill provides a command-line interface for GuanYuan Data (观远数据) API. It supports multiple authentication methods, automatic token management, card data retrieval, and CSV export with metadata generation.

Usage Instructions

When a user requests GuanYuan data operations:

  1. Choose authentication method:

    • Method 1: Provide loginId and password in config for automatic login
    • Method 2: Provide token directly in config file
    • Method 3: Use guanyuan token <token> command to set token interactively

  2. Get card data: Use guanyuan card <cardId> to retrieve data in JSON format

  3. Export to CSV: Use guanyuan csv <cardId> --output file.csv to export data

Authentication Methods

Method 1: Automatic Login with Credentials

{
  "baseUrl": "https://your-guanyuan-domain.com",
  "domain": "your-domain",
  "loginId": "your-login-id",
  "password": "your-password"
}

Then run: guanyuan login

Method 2: Direct Token in Config

{
  "baseUrl": "https://your-guanyuan-domain.com",
  "domain": "your-domain",
  "token": "your-token-here"
}

No login needed, directly use commands.

Method 3: Token Command (Interactive)

{
  "baseUrl": "https://your-guanyuan-domain.com",
  "domain": "your-domain"
}

Then run: guanyuan token <your-token> or guanyuan token (interactive)

Available Resources

Main Script

  • scripts/guanyuan.js: Main CLI tool
    • login(): Authenticate and save token
    • getCardData(cardId, options): Retrieve card data
    • convertToCSV(cardData, sampleRows): Convert data to CSV format
    • extractMetadata(cardData): Extract field metadata
    • saveCSVWithMetadata(csv, filename, metadata, cardId): Save CSV and metadata files
    • getValidToken(config): Auto-discover and use valid token from multiple sources

Configuration Files

  • ~/.guanyuan/config.json: API credentials and settings
    • Required: baseUrl, domain
    • Optional (one of): loginId + password, token, or none (use token command)
  • ~/.guanyuan/user.token: Stored authentication token (auto-managed)

Export Files

  • .csv: CSV data file
  • _meta.json: Metadata file with field information

References

  • references/README.md: Detailed user documentation in Chinese

Commands Reference

CommandDescriptionExample
initInitialize configuration (show setup instructions)guanyuan init
loginLogin with credentials from configguanyuan login
token [token]Set token (via parameter or interactive)guanyuan token eyJ0eX...
card <id>Get card data (JSON)guanyuan card abc123 --limit 50
csv <id>Export to CSVguanyuan csv abc123 --output data.csv
statusShow config and token statusguanyuan status
helpShow helpguanyuan help

Options Reference

Common Options

OptionDescriptionDefault
--view <GRAPH|GRID>Data view typeGRAPH
--limit <number>Number of rows100
--offset <number>Data offset0

CSV Export Options

OptionDescriptionDefault
--output <filename>Output to filestdout
--sample <number>Sample N rowsall rows

Example Prompts

  • "使用账号密码登录观远数据并获取卡片abc123的数据"
  • "使用token设置观远数据认证"
  • "Export card data to CSV with metadata"
  • "Get the first 50 rows of card l059d768f28bd404caf8df3e"
  • "导出卡片数据到CSV文件，只采样前10行"
  • "Check GuanYuan API configuration status"
  • "Save card data as query_data.csv with metadata"
  • "Set token for GuanYuan API without providing credentials"

Authentication Workflow

┌─────────────────────────────────────────────────────────────┐
│  User wants to access GuanYuan data                         │
└────────────────────┬────────────────────────────────────────┘
                     │
                     v
┌─────────────────────────────────────────────────────────────┐
│  Check ~/.guanyuan/user.token                               │
│  Is there a valid token?                                    │
└────────────────────┬────────────────────────────────────────┘
                     │
            ┌────────┴────────┐
            │                 │
         Yes │                 │ No
            │                 │
            v                 v
┌───────────────────┐  ┌──────────────────────────────────┐
│  Use saved token  │  │  Check config.json              │
└───────────────────┘  │  - Has loginId + password?       │
                      │  - Has token?                   │
                      │  - Neither? → Use token command  │
                      └────────────┬─────────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                Has Creds      Has Token    Neither
                    │              │              │
                    v              v              v
            ┌───────────┐  ┌───────────┐  ┌───────────────┐
            │  Auto     │  │  Use      │  │  Prompt user │
            │  Login    │  │  Config   │  │  to run      │
            │           │  │  Token   │  │  'guanyuan    │
            └───────────┘  └───────────┘  │   token'      │
                                         └───────────────┘

Metadata File Format

When exporting CSV with --output, a _meta.json file is automatically generated:

{
  "cardId": "card-id",
  "cardType": "CHART",
  "chartType": "PIVOT_TABLE",
  "view": "GRAPH",
  "exportTime": "2026-03-25T07:52:00.924Z",
  "totalRows": 10,
  "dataLimit": 10,
  "hasMoreData": false,
  "fields": [
    {
      "name": "字段显示名称",
      "originalName": "字段原始名称",
      "type": "STRING/TIMESTAMP/DOUBLE",
      "metaType": "DIM/METRIC",
      "fieldType": "dimension/metric",
      "fieldId": "field-id"
    }
  ]
}

Output Format

JSON Output

  • Full API response with chart data
  • Includes dimensions, metrics, and formatting info
  • Suitable for debugging and data inspection

CSV Output

  • Tabular format with headers
  • Dimensions first, then metrics
  • Proper CSV escaping for special characters
  • Metadata file with field types and descriptions

Token Management

Token Sources (Priority Order)

  1. ~/.guanyuan/user.token - Saved token (highest priority)
  2. config.json - Token field in config
  3. Auto-login - Using loginId + password from config

Token Behavior

  • With expireAt: Automatically validated against expiration time
  • Without expireAt: Used indefinitely (user-manually set tokens)
  • Expired/Invalid: Triggers auto-refresh (if credentials available) or prompts user

Manual Token Setting

# Via parameter
guanyuan token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

# Interactive mode
guanyuan token
# Then paste your token when prompted

Notes

  • Flexible Authentication: Three authentication methods for different use cases
  • Token Management: Tokens are automatically discovered from multiple sources
  • Auto-Login: Credentials-based auth with automatic token refresh
  • Password Handling: Passwords are automatically Base64 encoded before API call
  • URL Support: baseUrl can include protocol prefix (http:// or https://)
  • CSV Escaping: Special characters (commas, quotes, newlines) are properly escaped
  • File Safety: Existing files are overwritten without warning
  • Data Limits: Use --limit to control API response size
  • Sampling: Use --sample to export only N rows without fetching all data
  • No Credentials Required: Can work with just baseUrl + domain + token command

API References

More in Integrations