跳转到内容
ZGI Services

快速开始

  1. 申请服务凭据

    凭据由 ZGI 平台团队发放，格式为 zsk_ 开头的字符串，只在发放时展示一次。拿到后保存在服务端的密钥管理里，不要写进代码仓库或前端。

    终端窗口
    export ZGI_SERVICES_TOKEN='zsk_...'

  2. 查看你可以使用的能力

    终端窗口
    curl -sS https://services.zgi.im/v1/services \
      -H "Authorization: Bearer $ZGI_SERVICES_TOKEN"

    返回的 capabilities 只包含你的凭据有权限、且有可用数据源的能力。每个能力列出可选的数据源 providers 及其限制 limits。

  3. 第一次调用

    查询 2026 年国庆期间的中国节假日安排。invocation_id 由你生成，每次业务调用使用一个新的值。

    终端窗口
    curl -sS https://services.zgi.im/v1/public-holiday-queries \
      -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"invocation_id":"order-10086-1","provider":"holiday-cn","region":"CN","start_date":"2026-10-01","end_date":"2026-10-08"}'

    返回包含两部分：execution 是这次执行的记录（结果状态、用量），result 是查询结果。

    {
      "code": 0,
      "message": "success",
      "data": {
        "execution": {
          "id": "exe_01a12e52b912717faddb9b0372c2d034",
          "invocation_id": "order-10086-1",
          "outcome": "succeeded",
          "usage": { "provider_requests": 0, "units": [{ "name": "days", "value": 8, "source": "measured" }] }
        },
        "result": {
          "region": "CN",
          "days": [{ "date": "2026-10-01", "day_type": "public_holiday", "is_off_day": true, "holiday_name": "国庆节" }],
          "totals": { "workdays": 1, "off_days": 7 }
        }
      }
    }

  4. 用同一个 ID 再调一次

    重复提交同一个 invocation_id 会返回 409 EXECUTION.DUPLICATE_INVOCATION，并附上第一次的 execution，数据源不会被再次调用。这保证了网络重试不会造成重复计费。

  5. 在调用日志里找到它

    终端窗口
    curl -sS "https://services.zgi.im/v1/executions?invocation_id=order-10086-1" \
      -H "Authorization: Bearer $ZGI_SERVICES_TOKEN"