前提条件

在调用 API 之前，用户需要先在控制台平台上申请 API 密钥。API 密钥由 API 密钥 ID access_key_id 和 API 密钥的私钥 secret_access_key 两部分组成。

  • access_key_id 将作为参数包含在每一个请求中发送。

  • secret_access_key 用于生成请求串的签名。因此，出于安全考虑，智算提醒用户，需妥善保管 secret_access_key，请勿外传。

API 请求说明

请求限制

  • 配额限制

    为了保证用户能合理地使用 API，智算平台对每位用户的 API 访问配额进行了限制。如，初始用户为 2000次/3600秒，未来会开放更高的配额。

  • 返回数据集长度限制

    当获取资源列表时，系统返回的最大数据长度是 100，即便你传了更大的 limit。因此，当您需要获取很多的数据时，请根据返回的 total_sum 进行分批获取。

请求类型

智算平台的 API 请求主要分为 延迟请求 和 实时请求 两种。

  • 延迟请求

    对于耗时请求，无法实时返回执行结果，例如 CreateTrain 等。这些请求将以任务形式提交给智算平台的后台进行执行，并会在 API 请求的返回中返回任务 ID。

  • 实时请求

    对于非耗时请求，智算平台会直接返回操作结果。

请求结构

完整的 API 请求应该包含，API 入口、公共参数、指令参数。各部分说明如下。

名称 描述 说明

API 入口

API 调用的 Webservice 入口

格式为 https://ai.coreshub.cn/aicp。

公共参数

每个 API 调用都需要包含公共参数

-

指令参数

指令参数请参见每个指令的说明文档。

-

请求示例

这里以发送 GetTrainList 请求为例，说明一个 API 请求的完整结构。

https://ai.coreshub.cn:443/aicp/trains/namespaces/ALL/trains?access_key_id=QYACCESSKEYIDEXAMPLE
&image_name=
&limit=3
&name=
&namespace=ALL
&offset=0
&reverse=False
&zone=hd1
&signature=uNDWS%2BeFb3gr6sfklJVbk%2F335Oa26ljMifKhVNI6koSMI%3D

API 响应说明

响应结构

名称 类型 描述

ret_code

Integer

返回码是用来表示 API 请求的返回值。

  • 当 ret_code 的值是 0 的时候，表示 API 请求正常。

  • 当 ret_code 的值不为 0 的时候表示 API 请求错误。

message

string

对返回结果的描述性信息

meta

object

包含一些与请求相关的元数据

  • X_REQUEST_ID：string，此次请求的 ID。

  • X_REQUEST_USER：string，发起此次请求的用户相关信息。

data

array

该 API 请求的主要数据信息。具体内容需查看每个指令的说明文档。

count

Integer

总计数量。

响应示例

API 的返回结果为 JSON 结构，这里以 GetTrainList 请求返回为咧，说明一个 API 请求的返回消息的完整结构。

{
  "ret_code": 0,
  "message": "success",
  "meta": {
    "X_REQUEST_ID": "string",
    "X_REQUEST_USER": "string"
  },
  "data": [
    {
      "kuid": "48b20965-36e3-4b40-b910-a3df326539d2",
      "status": "Pending",
      "user_id": "usr-jaswGjDn",
      "created_at": "2023-12-26T10:17:33.150323",
      "updated_at": "2023-12-26T10:17:33.150323",
      "uuid": "eb1bc81c-a656-470d-85a7-13e1b25eb7f7",
      "name": "tf-job-example",
      "endpoint": "tfjobs",
      "namespace": "usr-jaswgjdn",
      "command": "python /var/tf_mnist/mnist_with_summaries.py",
      "image": "kubeflow/tf-mnist-with-summaries:latest",
      "image_type": "user",
      "restart_policy": "Never",
      "ttl_seconds_after_finished": 0,
      "replica_specs": [
        {
          "replicas": 2,
          "specs": "",
          "replica_type": "Worker"
        }
      ],
      "envs": [
        {
          "name": "env1",
          "value": "value1"
        }
      ]
    }
  ],
  "counts": 0
}