Kuscia Api 调用示例

隐语
中间件
-
- 字
2025-07-31 14:10

声明环境变量※

export CTR_CERTS_ROOT=/home/kuscia/var/certs

创建DomainDataSource※

  • alice
curl -k -X POST 'https://localhost:8082/api/v1/domaindatasource/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "domain_id": "alice",
  "datasource_id":"alice-ds-001",
  "type":"oss",
  "name": "aliceDS",
  "info": {
      "oss": {
          "endpoint": "http://192.168.32.128:9000",
          "bucket": "alice",
          "access_key_id":"kusciaadmin",
          "access_key_secret" :"kusciaadmin",
          "storage_type": "minio"
      }
  },
  "access_directly": true
}'
  • bob
curl -k -X POST 'https://localhost:8082/api/v1/domaindatasource/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "domain_id": "bob",
  "datasource_id":"bob-ds-001",
  "type":"oss",
  "name": "bobDS",
  "info": {
      "oss": {
          "endpoint": "http://192.168.32.128:9000",
          "bucket": "bob",
          "access_key_id":"kusciaadmin",
          "access_key_secret" :"kusciaadmin",
          "storage_type": "minio"
      }
  },
  "access_directly": true
}'

创建DomainData※

  • alice 
curl -k -X POST 'https://localhost:8082/api/v1/domaindata/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "domain_id": "alice",
  "domaindata_id": "alice-001",
  "datasource_id": "alice-ds-001",
  "name": "alice001",
  "type": "table",
  "relative_uri": "teams.csv",
  "columns": [
    {
      "name": "Id",
      "type": "int",
      "comment": "ID"
    },
    {
      "name": "TeamId",
      "type": "int",
      "comment": "队伍ID"
    },
    {
      "name": "TeamName",
      "type": "str",
      "comment": "队伍的全称或官方名称"
    },
    {
      "name": "TotalUSDPrize",
      "type": "float",
      "comment": "队伍在比赛中获得的总奖金（美元）"
    },
    {
      "name": "TotalTournaments",
      "type": "int",
      "comment": "队伍参加的总比赛次数"
    },
    {
      "name": "Game",
      "type": "str",
      "comment": "队伍主要参与的游戏名称"
    },
    {
      "name": "Genre",
      "type": "str",
      "comment": "游戏所属的类别（如第一人称射击、MOBA等）"
    }
  ]
}'
  • bob 
curl -k -X POST 'https://localhost:8082/api/v1/domaindata/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "domain_id": "bob",
  "domaindata_id": "bob-001",
  "datasource_id": "bob-ds-001",
  "name": "bob001",
  "type": "table",
  "relative_uri": "players.csv",
  "columns": [
    {
      "name": "Id",
      "type": "int",
      "comment": "ID"
    },
    {
      "name": "PlayerId",
      "type": "int",
      "comment": "选手ID"
    },
    {
      "name": "NameFirst",
      "type": "str",
      "comment": "选手的名字（西方习惯放在前的名）"
    },
    {
      "name": "NameLast",
      "type": "str",
      "comment": "选手的姓氏（西方习惯放在后的姓）"
    },
    {
      "name": "CurrentHandle",
      "type": "str",
      "comment": "选手当前使用的游戏ID/昵称"
    },
    {
      "name": "CountryCode",
      "type": "str",
      "comment": "选手国籍的ISO两位字母国家代码（如dk=丹麦）"
    },
    {
      "name": "TotalUSDPrize",
      "type": "float",
      "comment": "选手职业生涯获得的总奖金（美元），精确到小数点后两位"
    },
    {
      "name": "Game",
      "type": "str",
      "comment": "选手主要参赛的游戏全称"
    },
    {
      "name": "Genre",
      "type": "str",
      "comment": "游戏所属的竞技类别（如FPS第一人称射击）"
    }
  ]
}'

创建数据授权※

  • alice
curl -k -X POST 'https://localhost:8082/api/v1/domaindatagrant/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "domain_id": "alice",
  "domaindata_id": "alice-001",
  "domaindatagrant_id": "alice2bob001",
  "grant_domain": "bob"
}'
  • bob
curl -k -X POST 'https://localhost:8082/api/v1/domaindatagrant/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "domain_id": "bob",
  "domaindata_id": "bob-001",
  "domaindatagrant_id": "bob2alice001",
  "grant_domain": "alice"
}'

创建任务※

根据 initiator 决定发起方，即确定由哪方执行以下命令

curl -k -X POST 'https://localhost:8082/api/v1/job/create' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "job_id": "job-alice-bob-001",
  "initiator": "alice",
  "tasks": [
    {
      "task_id": "job-psi",
      "app_image": "secretflow-image",
      "parties": [
        {
          "domain_id": "alice",
          "role": "partner"
        },
        {
          "domain_id": "bob",
          "role": "partner"
        }
      ],
      "alias": "job-psi",
      "dependencies": [],
      "task_input_config": "{\"sf_datasource_config\":{\"alice\":{\"id\":\"alice-ds-001\"},\"bob\":{\"id\":\"bob-ds-001\"}},\"sf_cluster_desc\":{\"parties\":[\"alice\",\"bob\"],\"devices\":[{\"name\":\"spu\",\"type\":\"spu\",\"parties\":[\"alice\",\"bob\"],\"config\":\"{\\\"runtime_config\\\":{\\\"protocol\\\":\\\"REF2K\\\",\\\"field\\\":\\\"FM64\\\"},\\\"link_desc\\\":{\\\"connect_retry_times\\\":60,\\\"connect_retry_interval_ms\\\":1000,\\\"brpc_channel_protocol\\\":\\\"http\\\",\\\"brpc_channel_connection_type\\\":\\\"pooled\\\",\\\"recv_timeout_ms\\\":1200000,\\\"http_timeout_ms\\\":1200000}}\"},{\"name\":\"heu\",\"type\":\"heu\",\"parties\":[\"alice\",\"bob\"],\"config\":\"{\\\"mode\\\": \\\"PHEU\\\", \\\"schema\\\": \\\"paillier\\\", \\\"key_size\\\": 2048}\"}],\"ray_fed_config\":{\"cross_silo_comm_backend\":\"brpc_link\"}},\"sf_node_eval_param\":{\"domain\":\"data_prep\",\"name\":\"psi\",\"version\":\"0.0.5\",\"attr_paths\":[\"protocol\",\"sort_result\",\"allow_duplicate_keys\",\"allow_duplicate_keys/yes/join_type\",\"allow_duplicate_keys/yes/join_type/left_join/left_side\",\"input/receiver_input/key\",\"input/sender_input/key\"],\"attrs\":[{\"s\":\"PROTOCOL_ECDH\"},{\"b\":true},{\"s\":\"yes\"},{\"s\":\"left_join\"},{\"ss\":[\"alice\"]},{\"ss\":[\"Game\"]},{\"ss\":[\"Game\"]}]},\"sf_input_ids\":[\"alice-001\",\"bob-001\"],\"sf_output_ids\":[\"psi-output\"],\"sf_output_uris\":[\"psi-output.csv\"]}",
      "priority": 100
    },
    {
      "task_id": "job-split",
      "app_image": "secretflow-image",
      "parties": [
        {
          "domain_id": "alice",
          "role": "partner"
        },
        {
          "domain_id": "bob",
          "role": "partner"
        }
      ],
      "alias": "job-split",
      "dependencies": [
        "job-psi"
      ],
      "task_input_config": "{\"sf_datasource_config\":{\"alice\":{\"id\":\"alice-ds-001\"},\"bob\":{\"id\":\"bob-ds-001\"}},\"sf_cluster_desc\":{\"parties\":[\"alice\",\"bob\"],\"devices\":[{\"name\":\"spu\",\"type\":\"spu\",\"parties\":[\"alice\",\"bob\"],\"config\":\"{\\\"runtime_config\\\":{\\\"protocol\\\":\\\"REF2K\\\",\\\"field\\\":\\\"FM64\\\"},\\\"link_desc\\\":{\\\"connect_retry_times\\\":60,\\\"connect_retry_interval_ms\\\":1000,\\\"brpc_channel_protocol\\\":\\\"http\\\",\\\"brpc_channel_connection_type\\\":\\\"pooled\\\",\\\"recv_timeout_ms\\\":1200000,\\\"http_timeout_ms\\\":1200000}}\"},{\"name\":\"heu\",\"type\":\"heu\",\"parties\":[\"alice\",\"bob\"],\"config\":\"{\\\"mode\\\": \\\"PHEU\\\", \\\"schema\\\": \\\"paillier\\\", \\\"key_size\\\": 2048}\"}],\"ray_fed_config\":{\"cross_silo_comm_backend\":\"brpc_link\"}},\"sf_node_eval_param\":{\"domain\":\"data_prep\",\"name\":\"train_test_split\",\"version\":\"0.0.1\",\"attr_paths\":[\"train_size\",\"test_size\",\"random_state\",\"shuffle\"],\"attrs\":[{\"f\":0.75},{\"f\":0.25},{\"i64\":1234},{\"b\":true}]},\"sf_output_uris\":[\"train-dataset.csv\",\"test-dataset.csv\"],\"sf_output_ids\":[\"train-dataset\",\"test-dataset\"],\"sf_input_ids\":[\"psi-output\"]}",
      "priority": 100
    }
  ]
}'

删除JOB※

⚠️仅能由发起方进行删除⚠️

curl -k -X POST 'https://localhost:8082/api/v1/job/delete' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "job_id": "job-alice-bob-001"
}'

查询JOB状态※

curl -k -X POST 'https://localhost:8082/api/v1/job/query' \
 --header "Token: $(cat ${CTR_CERTS_ROOT}/token)" \
 --header 'Content-Type: application/json' \
 --cert ${CTR_CERTS_ROOT}/kusciaapi-server.crt \
 --key ${CTR_CERTS_ROOT}/kusciaapi-server.key \
 --cacert ${CTR_CERTS_ROOT}/ca.crt \
 -d '{
  "job_id": "job-alice-bob-001"
}'