# 运行作业 - RunRayJob #### 功能介绍 运行Ray作业。本接口为异步接口，当前运行作业请求下发成功后会返回job_id，此时运行作业并没有立即完成，需要通过调用查看Ray作业详情查询Job状态，当Job状态为SUCCEEDED时代表运行作业成功。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### URI POST /v2/workspaces/{workspace_id}/ray-jobs 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | workspace_id | 是 | String | **参数解释**：工作空间ID。 **约束限制**：不涉及。 **取值范围**：长度为1\~36的英文字符、数字和中划线的组合。 **默认取值**：不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**：租户Token。 **约束限制**：不涉及。 **取值范围**：长度不超过65534个字符。 **默认取值**：不涉及。 | | X-Client-Token | 否 | String | **参数解释**：作业事务 ID，防止重复提交。 **约束限制**：不涉及。 **取值范围**：长度不超过65534个字符。 **默认取值**：不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释**：Job名称。 **约束限制**：不涉及。 **取值范围**：长度为1\~47的英文字母、数字、中划线。 **默认取值**：不涉及。 | | endpoint_name | 是 | String | **参数解释**：端点名称。 **约束限制**：不涉及。 **取值范围**：长度为1\~63个字符。包含小写字母、数字、中划线的组合。字母开头、字母或数字结尾。 **默认取值**：不涉及。 | | config | 是 | [RayJobConfig] object | **参数解释**：Ray作业类型的配置信息。 **约束限制**：不涉及。 | | description | 否 | String | **参数解释**：描述信息。 **约束限制**：不涉及。 **取值范围**：长度为0\~1024的中文、英文字母、数字、下划线、中划线、点号、空格的组合。 **默认取值**：不涉及。 | 表4RayJobConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | entrypoint | 是 | String | **参数解释**：运行作业主脚本。 **约束限制**：不涉及。 **取值范围**：长度为1\~102400个字符。 **默认取值**：不涉及。 | | runtime_env | 否 | [RuntimeEnv] object | **参数解释**：作业的运行时环境配置。 **约束限制**：不涉及。 **取值范围**：可选参数有： - working_dir：代码将在其中运行的工作目录，必须是远程URI，如OBS路径。 - pip：要安装的pip软件包列表。 - env_vars：要设置的环境变量。 **默认取值**：不涉及。 | | image | 否 | [V2ImageBriefInfo] object | **参数解释**：镜像信息。 **约束限制**：仅提交作业到RayJob端点时配置。 | | resource_config | 否 | [RayResourceConfig] object | **参数解释**：Ray节点资源配置。 **约束限制**：仅提交作业到RayJob端点时配置。 | | rayjob_strategy | 否 | [RayJobStrategy] object | **参数解释**：Ray Job提交策略。 **约束限制**：不涉及。 | | history_server_enabled | 否 | Boolean | **参数解释**：指示该作业是否启用了历史服务器（History Server）功能。 **约束限制**：不涉及。 **取值范围**： - true：启用History Server。 - false：禁用History Server。 **默认取值**：false。 | 表5RuntimeEnv | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | working_dir | 否 | String | **参数解释**：代码将在其中运行的工作目录。 **约束限制**：必须是远程URI，如OBS路径。 **取值范围**：最小长度1，最大长度2048。 **默认取值**：不涉及。 | | pip | 否 | Array of strings | **参数解释**：要安装的pip软件包列表。 **约束限制**：最小个数0，最大个数1023。 | | env_vars | 否 | Map\ | **参数解释**：要设置的环境变量。 **约束限制**：不涉及。 | | config | 否 | Map\ | **参数解释**：运行环境的配置。 **约束限制**：不涉及。 **取值范围**：不涉及。 **默认取值**：不涉及。 | 表6V2ImageBriefInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image_id | 是 | String | **参数解释**：用户作业使用的镜像ID。 **约束限制**：仅提交作业到RayJob端点时配置。 **取值范围**：不涉及。 **默认取值**：不涉及。 | | image_version_id | 是 | String | **参数解释**：镜像版本。 **约束限制**：仅提交作业到RayJob端点时配置。 **取值范围**：不涉及。 **默认取值**：不涉及。 | 表7RayResourceConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | head_resource_spec | 是 | [RayHeadResourceSpec] object | **参数解释**：head资源配置。 **约束限制**：仅提交作业到RayJob端点时配置。 | | worker_resource_spec | 是 | Array of [RayWorkerResourceSpec] objects | **参数解释**：worker资源配置。 **约束限制**：仅提交作业到RayJob端点时配置。 | 表8RayHeadResourceSpec | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | cpu | 是 | Integer | **参数解释**：CPU核数量，单位为毫核。 **约束限制**：不涉及。 **取值范围**：最小值为1000。 **默认取值**：不涉及。 | | memory | 是 | Integer | **参数解释**：单个head内存大小，单位MB。 **约束限制**：不涉及。 **取值范围**：最小值为1024。 **默认取值**：不涉及。 | | gpu | 否 | Double | **参数解释**：节点的GPU数量。 **约束限制**：不涉及。 **取值范围**：需配置为大于0的浮点数。 **默认取值**：不涉及。 | | npu | 否 | Double | **参数解释**：节点的NPU数量。 **约束限制**：不涉及。 **取值范围**：需配置为大于0的浮点数。 **默认取值**：不涉及。 | 表9RayWorkerResourceSpec | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | cpu | 是 | Integer | **参数解释**：CPU核数量，单位为毫核。 **约束限制**：不涉及。 **取值范围**：最小值为1000。 **默认取值**：不涉及。 | | memory | 是 | Integer | **参数解释**：内存大小，单位MB。 **约束限制**：不涉及。 **取值范围**：最小值为1024。 **默认取值**：不涉及。 | | gpu | 否 | Double | **参数解释**：节点的GPU数量。 **约束限制**：不涉及。 **取值范围**：需配置为大于0的浮点数。 **默认取值**：不涉及。 | | npu | 否 | Double | **参数解释**：节点的NPU数量。 **约束限制**：不涉及。 **取值范围**：需配置为大于0的浮点数。 **默认取值**：不涉及。 | | worker_replicas | 否 | Integer | **参数解释**：Worker副本数量。 **约束限制**：不涉及。 **取值范围**：1\~64。 **默认取值**：不涉及。 | | enable_autoscaling | 是 | Boolean | **参数解释**：是否开启worker节点的弹性伸缩。 **约束限制**：不涉及。 **取值范围**：可选值有： - true：开启弹性伸缩。取该值时worker_min_replicas和worker_max_replicas必须设置。 - false：不开启弹性伸缩。取该值时worker_replicas必须设置。 **默认取值**：false。 | | worker_min_replicas | 否 | Integer | **参数解释**：Worker最小副本数量。 **约束限制**：不涉及。 **取值范围**：0\~64。 **默认取值**：不涉及。 | | worker_max_replicas | 否 | Integer | **参数解释**：Worker最大副本数量。 **约束限制**：不涉及。 **取值范围**：1\~64。 **默认取值**：不涉及。 | 表10RayJobStrategy | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | queued_timeout | 否 | Integer | **参数解释**：作业提交超时时间，如果超过此时间作业仍未运行，则作业失败。 **约束限制**：不涉及。 **取值范围**：最大值为1天，最小值为10分钟。单位：分钟。 **默认取值**：3小时。 | | running_timeout | 否 | Integer | **参数解释**：作业运行超时时间，如果超过此时间作业还未运行结束，则作业会取消运行，并标记失败。 **约束限制**：不涉及。 **取值范围**：最小时间为10分钟，最大时间为7天。 **默认取值**：-1，表示没有配置作业运行超时时间。 | #### 响应参数 **状态码：202** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | job_id | String | **参数解释**：作业ID。 **取值范围**：长度为1\~36的英文字符、数字和中划线的组合。 | **状态码：400** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：401** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：404** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：408** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：500** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | #### 请求示例 运行Ray作业。本接口为异步接口，当前运行作业请求下发成功后会返回job_id，此时运行作业并没有立即完成，需要通过调用查看Ray作业详情查询Job状态，当状态为SUCCEEDED时代表运行作业成功。 ``` POST /v2/workspaces/{workspace_id}/ray-jobs { "name" : "name", "description" : "description", "endpoint_name" : "ray", "config" : { "entrypoint" : "python3 -m estimate_pi 1000000", "runtime_env" : { "working_dir" : "obs://ray-shared-csc/ray-job-code.zip", "pip" : [ "numpy=1.16.1" ], "env_vars" : { "additionalProp1" : "value1", "additionalProp2" : "value2", "additionalProp3" : "value3" } } } } ``` #### 响应示例 **状态码：202** 请求下发成功。 ``` { "job_id" : "ac8111bf-3601-4905-8ddd-b41d3e636a4e" } ``` **状态码：400** 非法请求。 ``` { "error_code" : "common.01000001", "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException" } ``` **状态码：401** 未经授权。 ``` { "error_code" : "APIG.1002", "error_msg" : "Incorrect token or token resolution failed" } ``` **状态码：403** 请求被拒绝访问。 ``` { "error" : { "code" : "403", "message" : "X-Auth-Token is invalid in the request", "title" : "Forbidden" }, "error_code" : 403, "error_msg" : "X-Auth-Token is invalid in the request", "title" : "Forbidden" } ``` **状态码：404** 所请求的资源不存在。 ``` { "error_code" : "common.01000001", "error_msg" : "response status exception, code: 404" } ``` **状态码：408** 请求超时。 ``` { "error_code" : "common.00000408", "error_msg" : "timeout exception occurred" } ``` **状态码：500** 服务器内部错误。 ``` { "error_code" : "common.00000500", "error_msg" : "internal error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 202 | 请求下发成功。 | | 400 | 非法请求。 | | 401 | 未经授权。 | | 403 | 请求被拒绝访问。 | | 404 | 所请求的资源不存在。 | | 408 | 请求超时。 | | 500 | 服务器内部错误。 |