华为云用户手册

使用案例 from modelarts import workflow as wf condition_equal = wf.steps.Condition(condition_type=wf.steps.ConditionTypeEnum.EQ, left=wf.Placeholder(name="is_true", placeholder_type=wf.PlaceholderType.BOOL), right=True) condition_step = wf.steps.ConditionStep( name="condition_step", conditions=[condition_equal], if_then_steps=["training_job_1"], else_then_steps=["training_job_2"], ) # 构建一个OutputStorage对象，对训练输出目录做统一管理 storage = wf.data.OutputStorage(name="storage_name", title="title_info", description="description_info") # name字段必填，title, description可选填 # 定义输入的OBS对象 obs_data = wf.data.OBSPlaceholder(name="obs_placeholder_name", object_type="directory") # 通过JobStep来定义一个训练节点，并将训练结果输出到OBS job_step_1 = wf.steps.JobStep( name="training_job_1", # 训练节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复 title="图像分类训练", # 标题信息，不填默认使用name algorithm=wf.AIGalleryAlgorithm( subscription_id="subscription_id", # 算法订阅ID item_version_id="item_version_id", # 算法订阅版本ID，也可直接填写版本号 parameters=[] ), # 训练使用的算法对象，示例中使用AIGallery订阅的算法；部分算法超参的值如果无需修改，则在parameters字段中可以不填写，系统自动填充相关超参值 inputs=wf.steps.JobInput(name="data_url", data=obs_data), # JobStep的输入在运行时配置；data字段也可使用data=wf.data.OBSPath(obs_path="fake_obs_path")表示 outputs=wf.steps.JobOutput(name="train_url", obs_config=wf.data.OBSOutputConfig(obs_path=storage.join("directory_path"))), # JobStep的输出 spec=wf.steps.JobSpec( resource=wf.steps.JobResource( flavor=wf.Placeholder(name="train_flavor", placeholder_type=wf.PlaceholderType.JSON, description="训练资源规格") ) ), # 训练资源规格信息 depend_steps=[condition_step] ) # 通过JobStep来定义一个训练节点，并将训练结果输出到OBS job_step_2 = wf.steps.JobStep( name="training_job_2", # 训练节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复 title="图像分类训练", # 标题信息，不填默认使用name algorithm=wf.AIGalleryAlgorithm( subscription_id="subscription_id", # 算法订阅ID item_version_id="item_version_id", # 算法订阅版本ID，也可直接填写版本号 parameters=[] ), # 训练使用的算法对象，示例中使用AIGallery订阅的算法；部分算法超参的值如果无需修改，则在parameters字段中可以不填写，系统自动填充相关超参值 inputs=wf.steps.JobInput(name="data_url", data=obs_data), # JobStep的输入在运行时配置；data字段也可使用data=wf.data.OBSPath(obs_path="fake_obs_path")表示 outputs=wf.steps.JobOutput(name="train_url", obs_config=wf.data.OBSOutputConfig(obs_path=storage.join("directory_path"))), # JobStep的输出 spec=wf.steps.JobSpec( resource=wf.steps.JobResource( flavor=wf.Placeholder(name="train_flavor", placeholder_type=wf.PlaceholderType.JSON, description="训练资源规格") ) ), # 训练资源规格信息 depend_steps=[condition_step] ) # 定义模型名称参数 model_name = wf.Placeholder(name="placeholder_name", placeholder_type=wf.PlaceholderType.STR) model_step = wf.steps.ModelStep( name="model_registration", # 模型注册节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复 title="模型注册", # 标题信息 inputs=wf.steps.ModelInput(name='model_input', data=wf.data.DataConsumptionSelector(data_list=[job_step_1.outputs["train_url"].as_input(), job_step_2.outputs["train_url"].as_input()])), # 选择job_step_1或者job_step_2的输出作为输入 outputs=wf.steps.ModelOutput(name='model_output', model_config=wf.steps.ModelConfig(model_name=model_name, model_type="TensorFlow")), # ModelStep的输出 depend_steps=[job_step_1, job_step_2] # 依赖的作业类型节点对象 )# job_step是wf.steps.JobStep的 实例对象，train_url是wf.steps.JobOutput的name字段值 workflow = wf.Workflow(name="data-select-demo", desc="this is a test workflow", steps=[condition_step, job_step_1, job_step_2, model_step], storages=storage ) 案例中的Workflow存在两个并行分支，并且同时只有一条分支会执行，由condition_step的相关配置决定。model_step的输入来源为job_step_1或者job_step_2的输出，当job_step_1节点所在分支执行，job_step_2节点所在分支跳过时，model_step节点执行时自动获取job_step_1的输出作为输入，反之自动获取job_step_2的输出作为输入。

Data 数据对象用于节点的输入，主要可分为以下三种类型： 真实的数据对象，在工作流构建时直接指定： Dataset：用于定义已有的数据集，常用于数据标注，模型训练等场景 LabelTask: 用于定义已有的标注任务，常用于数据标注，数据集版本发布等场景 OBSPath：用于定义指定的OBS路径，常用于模型训练，数据集导入，模型导入等场景 ServiceData：用于定义一个已有的服务，只用于服务更新的场景 SWRImage：用于定义已有的SWR路径，常用于模型注册场景 GalleryModel：用于定义从gallery订阅的模型，常用于模型注册场景 占位符式的数据对象，在工作流运行时指定： DatasetPlaceholder：用于定义在运行时需要确定的数据集，对应Dataset对象，常用于数据标注，模型训练等场景 LabelTaskPlaceholder：用于定义在运行时需要确定的标注任务，对应LabelTask对象，常用于数据标注，数据集版本发布等场景 OBSPlaceholder：用于定义在运行时需要确定的OBS路径，对应OBSPath对象，常用于模型训练，数据集导入，模型导入等场景 ServiceUpdatePlaceholder：用于定义在运行时需要确定的已有服务，对应ServiceData对象，只用于服务更新的场景 SWRImagePlaceholder：用于定义在运行时需要确定的SWR路径，对应SWRImage对象，常用于模型注册场景 ServiceInputPlaceholder：用于定义在运行时需要确定服务部署所需的模型相关信息，只用于服务部署及服务更新场景 DataSelector：支持多种数据类型的选择，当前仅支持在JobStep节点中使用（仅支持选择OBS或者数据集） 数据选择对象： DataConsumptionSelector：用于在多个依赖节点的输出中选择一个有效输出作为数据输入，常用于存在条件分支的场景中（在构建工作流时未能确定数据输入来源为哪个依赖节点的输出，需根据依赖节点的实际执行情况进行自动选择） 表1 Dataset 属性 描述 是否必填 数据类型 dataset_name 数据集名称 是 str version_name 数据集版本名称 否 str 示例： example = Dataset(dataset_name = "**", version_name = "**") # 通过ModelArts的数据集，获取对应的数据集名称及相应的版本名称。 当Dataset对象作为节点的输入时，需根据业务需要自行决定是否填写version_name字段（比如LabelingStep、ReleaseDatasetStep不需要填写，JobStep必须填写）。 表2 LabelTask 属性 描述 是否必填 数据类型 dataset_name 数据集名称 是 str task_name 标注任务名称 是 str 示例： example = LabelTask(dataset_name = "**", task_name = "**") # 通过ModelArts的新版数据集，获取对应的数据集名称及相应的标注任务名称 表3 OBSPath 属性 描述 是否必填 数据类型 obs_path OBS路径 是 str，Storage 示例： example = OBSPath(obs_path = "**") # 通过 对象存储服务 ，获取已存在的OBS路径值 表4 ServiceData 属性 描述 是否必填 数据类型 service_id 服务的ID 是 str 示例： example = ServiceData(service_id = "**") # 通过ModelArts的在线服务，获取对应服务的服务ID，描述指定的在线服务。用于服务更新的场景。 表5 SWRImage 属性 描述 是否必填 数据类型 swr_path 容器镜像的SWR路径 是 str 示例： example = SWRImage(swr_path = "**") # 容器镜像地址，用于模型注册节点的输入 表6 GalleryModel 属性 描述 是否必填 数据类型 subscription_id 订阅模型的订阅ID 是 str version_num 订阅模型的版本号 是 str 示例： example = GalleryModel(subscription_id="**", version_num="**") # 订阅的模型对象，用于模型注册节点的输入 表7 DatasetPlaceholder 属性 描述 是否必填 数据类型 name 名称 是 str data_type 数据类型 否 DataTypeEnum delay 标志数据对象是否在节点运行时配置，默认为False 否 bool default 数据对象的默认值 否 Dataset 示例： example = DatasetPlaceholder(name = "**", data_type = DataTypeEnum.IMAGE_CLASSIFICATION) # 数据集对象的占位符形式，可以通过指定data_type限制数据集的数据类型 表8 OBSPlaceholder 属性 描述 是否必填 数据类型 name 名称 是 str object_type 表示OBS对象类型，仅支持"file"或者"directory" 是 str delay 标志数据对象是否在节点运行时配置，默认为False 否 bool default 数据对象的默认值 否 OBSPath 示例： example = OBSPlaceholder(name = "**", object_type = "directory" ) # OBS对象的占位符形式，object_type只支持两种类型， "file" 以及 "directory" 表9 LabelTaskPlaceholder 属性 描述 是否必填 数据类型 name 名称 是 str task_type 表示标注任务的类型 否 LabelTaskTypeEnum delay 标志数据对象是否在节点运行时配置，默认为False 否 bool 示例： example = LabelTaskPlaceholder(name = "**") # LabelTask对象的占位符形式 表10 ServiceUpdatePlaceholder 属性 描述 是否必填 数据类型 name 名称 是 str delay 标志数据对象是否在节点运行时配置，默认为False 否 bool 示例： example = ServiceUpdatePlaceholder(name = "**") # ServiceData对象的占位符形式，用于服务更新节点的输入 表11 SWRImagePlaceholder 属性 描述 是否必填 数据类型 name 名称 是 str delay 标志数据对象是否在节点运行时配置，默认为False 否 bool 示例： example = SWRImagePlaceholder(name = "**" ) # SWRImage对象的占位符形式，用于模型注册节点的输入 表12 ServiceInputPlaceholder 属性 描述 是否必填 数据类型 name 名称 是 str model_name 模型名称 是 str或者Placeholder model_version 模型版本 否 str envs 环境变量 否 dict delay 服务部署相关信息是否在节点运行时配置，默认为True 否 bool 示例： example = ServiceInputPlaceholder(name = "**" , model_name = "model_name") # 用于服务部署或者服务更新节点的输入 表13 DataSelector 属性 描述 是否必填 数据类型 name 名称 是 str data_type_list 支持的数据类型列表，当前仅支持obs、dataset 是 list delay 标志数据对象是否在节点运行时配置，默认为False 否 bool 示例： example = DataSelector(name = "**" ,data_type_list=["obs", "dataset"]) # 用于作业类型节点的输入 表14 DataConsumptionSelector 属性 描述 是否必填 数据类型 data_list 依赖节点的输出数据对象列表 是 list 示例： example = DataConsumptionSelector(data_list=[step1.outputs["step1_output_name"].as_input(), step2.outputs["step2_output_name"].as_input()]) # 从step1以及step2中选择有效输出作为输入，当step1跳过无输出，step2执行有输出时，将step2的有效输出作为输入（需保证data_list中同时只有一个有效输出） 父主题： 核心概念

其他操作 您可以在“会议用户”界面用户列表所在行的右侧单击“修改”进行编辑，也可以单击“移除”移除用户，还可以单击“更多”重置用户密码、停用/启用该用户的账号。 图6 管理用户 您可以勾选“通讯录排序号”查看已设置序号的用户。 图7 查看用户的通讯录排序号 您可以单击“导出”查看用户数据，如下图所示。 图8 导出用户信息 您还可以在“会议用户”界面，单击“待定”，来查看未接受邀请的用户，并进行重新发送邀请、删除的操作。 图9 管理待定用户

会前操作 完成配对后，可在移动端的控制器对SmartRooms进行加入会议、发起会议等会前操作。 加入会议 从会议日程入会：在会议日程中单击“加入”进入会议。 受邀入会：收到会议邀请时单击按钮入会。 使用会议号和密码入会：从主持人或其他与会者获取会议号和密码，单击“加入会议”，输入会议号和密码入会。 发起会议：单击“发起会议”可创建会议。 共享投屏：单击“共享投屏”可根据引导进行投屏。 图4 SmartRooms控制器会前操作

会控操作 完成配对后，可在移动端的控制器对SmartRooms进行音视频设置、投屏、切换会中视图等会控操作。 音视频设置 单击“静音”或“开启视频”按钮，可开启或关闭麦克风、摄像头。 滑动音量条可调整扬声器的音量。 共享：单击“共享”可根据引导进行投屏。 与会者：单击“与会者”可查看与会者列表。 邀请：单击“邀请”打开会议信息弹窗，可扫码分享会议信息、获取会议号和密码邀请他人入会。 视图：单击“视图”，可将会中视图切换为演讲者视图、画中画视图或画廊视图等。 主持人控制：单击“主持人控制”打开弹窗，可开启等候室、允许解除静音、设置视频权限等。 离开：单击“离开”，若SmartRooms是会议主持人，可选择离开会议或结束会议；若SmartRooms是与会者，可选择离开会议。 图5 SmartRooms控制器会控操作

响应示例 状态码： 200 OK { "entities" : [ { "mention" : "李娜", "offset" : 0, "entity_id" : "6939670486880563336", "entity_title" : "李娜（流行歌手、佛门女弟子）" }, { "mention" : "青藏高原", "offset" : 4, "entity_id" : "8654144631589645401", "entity_title" : "青藏高原（李娜演唱歌曲）" } ] } 状态码： 400 Bad Request { "error_code" : "KGP.2007", "error_msg" : "kg not found" } 状态码： 403 Forbidden { "error_code" : "KGP.0004", "error_msg" : "Auth failed" }

URI POST /v1/{project_id}/kg/kg-instances/{kg_id}/apps/entity-linking 表1 路径参数 参数 是否必选 参数类型 描述 kg_id 是 String 知识图谱 ID。在KG服务控制台“我的图谱”页面，单击图谱名称，进入图谱详情页左上角获取知识图谱ID。 project_id 是 String 用户项目ID。获取方法请参见获取项目ID。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 entities Array of EntityLinkingRespEntityMention objects 实体链接结果。 表4 EntityLinkingRespEntityMention 参数 参数类型 描述 entity_id String 链接到的图谱节点对应的实体id。 entity_title String 链接到的图谱节点对应的实体名称。 mention String 实体名称。 offset Integer 实体文本在待分析文本中的起始位置。

请求示例 分析识别文本为 "李娜唱的青藏高原真好听"的实体 https://nlp-ext.cn-north-4.myhuaweicloud.com/v1/1604d8170cd84440a81281e5a3a04f8b/kg/kg-instances/6cdcea01-bac0-48f6-acb5-9385ea3e24ad/apps/entity-linking { "text" : "李娜唱的青藏高原真好听" }

基本概念 账号 用户注册华为云时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。 用户 由账号在 IAM 中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。 在我的凭证下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。 区域 指云资源所在的物理位置，同一区域内可用区间内网互通，不同区域间内网不互通。通过在不同地区创建云资源，可以将应用程序设计的更接近特定客户的要求，或满足不同地区的法律或其他要求。 可用区 一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。 项目 华为云的区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。 图1 项目隔离模型 同样在我的凭证下，您可以查看项目ID。 企业项目 企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。 关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理服务用户指南》。 父主题： 使用前必读

响应示例 状态码： 200 OK { "answer" : "小明的身高是175cm。", "session_id" : "b22ce1e7-72e6-4846-86e5-65f66a882989", "frame" : [ { "formatted_question" : "[小明]的[身高]", "match_type" : "SYS_TEMPLATE", "template_id" : "77396e46-6eec-49bb-bb84-84faa4229090", "template_name" : "xx实体的xx属性", "template_score" : 1.0, "query" : "g.V('6155801785020056890').valueMap('name', '身高').path()", "result" : { "vertices" : [ { "id" : "6155801785020056890", "label" : "人物" } ], "runtime" : 0.007594787999999999, "results" : [ { "name" : [ "小明" ], "身高" : [ "175cm" ] } ] }, "answer" : "小明的身高是175cm。" } ] } 状态码： 400 Bad Request { "error_code" : "KGP.2007", "error_msg" : "kg not found" } 状态码： 403 Forbidden { "error_code" : "KGP.0004", "error_msg" : "Auth failed" }

请求示例 进行KBQA会话，询问小明的身高 https://nlp-ext.cn-north-4.myhuaweicloud.com/v1/1604d8170cd84440a81281e5a3a04f8b/kg/kg-instances/6cdcea01-bac0-48f6-acb5-9385ea3e24ad/apps/kbqa/converse { "session_id" : "b22ce1e7-72e6-4846-86e5-65f66a882989", "query" : "小明的身高" }

URI POST /v1/{project_id}/kg/kg-instances/{kg_id}/apps/kbqa/converse 表1 路径参数 参数 是否必选 参数类型 描述 kg_id 是 String 知识图谱ID。在KG服务控制台“我的图谱”页面，单击图谱名称，进入图谱详情页左上角获取知识图谱ID。 project_id 是 String 用户项目ID。获取方法请参见获取项目ID。

响应示例 状态码： 200 OK { "data" : { "vertices" : [ { "id" : "9070097808196707553", "label" : "电影", "properties" : { "上映时间" : [ "1958年1月16日" ], "name" : [ "保卫和平" ], "票房" : [ "39.04亿" ] } } ], "runtime" : 0.02850004 } } 状态码： 400 Bad Request { "error_code" : "KGP.2003", "error_msg" : "Gremlin query return error" } 状态码： 403 Forbidden { "error_code" : "KGP.0004", "error_msg" : "Auth failed" } 状态码： 500 Internal Server Error { "error_code" : "KGP.9001", "error_msg" : "Internal server error." }

请求示例 查询关联实体，最多返回两条结果 https://nlp-ext.cn-north-4.myhuaweicloud.com/v1/1604d8170cd84440a81281e5a3a04f8b/kg/kg-instances/6cdcea01-bac0-48f6-acb5-9385ea3e24ad/entities/8039469283414000536/adjacent-entities?offset=0&limit=2

URI GET /v1/{project_id}/kg/kg-instances/{kg_id}/entities/{entity_id}/adjacent-entities 表1 路径参数 参数 是否必选 参数类型 描述 entity_id 是 String 实体ID。 kg_id 是 String 知识图谱ID。在KG服务控制台“我的图谱”页面，单击图谱名称，进入图谱详情页左上角获取知识图谱ID。 project_id 是 String 用户项目ID。获取方法请参见获取项目ID。 表2 Query参数 参数 是否必选 参数类型 描述 label 否 String 具有一跳关系的实体类型。默认为空，即查询有一跳关系的所有类型的实体。 说明： N跳关系说明：如果从一个实体A出发，经过N条关系（不论方向），能够到达实体B，则实体A、B之间是N跳关系。 特别地，如果两个实体之间是一跳关系，说明两个实体之间通过一条关系直接相连。 limit 否 Integer 最大返回结果条数，默认为10，最大为100。 最小值：0 最大值：100 缺省值：10 offset 否 Integer 翻页偏移量，默认为0。 最小值：0 最大值：100 缺省值：0 relation_name 否 String 需要查询的关系名称。默认为空，即查询所有一跳关系。

响应示例 状态码： 200 OK { "entity" : { "id" : "8039469283414000536", "label" : "人物", "properties" : { "职业" : [ "演员，歌手" ], "出生日期" : [ "1980年12月13日" ], "name" : [ "计广" ], "国籍" : [ "中国" ] } }, "results" : [ { "direction" : "IN", "adjacent_entity_id" : "8886811463068384992", "edge" : { "source_id" : "8886811463068384992", "target_id" : "8039469283414000536", "relation_label" : "主演", "properties" : null } }, { "direction" : "IN", "adjacent_entity_id" : "7146030181767445493", "edge" : { "source_id" : "7146030181767445493", "target_id" : "8039469283414000536", "relation_label" : "主演", "properties" : null } } ], "total" : 20, "count" : 2 }

请求示例 过滤查询名称为一条牧羊犬的电影 https://nlp-ext.cn-north-4.myhuaweicloud.com/v1/1604d8170cd84440a81281e5a3a04f8b/kg/kg-instances/6cdcea01-bac0-48f6-acb5-9385ea3e24ad/entities/property-query { "labels" : [ "电影" ], "offset" : 0, "limit" : 1, "conditions" : [ { "property_name" : "name", "property_values" : [ "一条牧羊犬" ] } ] }

URI POST /v1/{project_id}/kg/kg-instances/{kg_id}/entities/property-query 表1 路径参数 参数 是否必选 参数类型 描述 kg_id 是 String 知识图谱ID。在KG服务控制台“我的图谱”页面，单击图谱名称，进入图谱详情页左上角获取知识图谱ID。 project_id 是 String 用户项目ID。获取方法请参见获取项目ID。

响应示例 状态码： 200 OK { "count" : 1, "entities" : [ { "id" : "-8886811463068384992", "label" : "电影", "properties" : { "上映时间" : [ "1982年4月22日" ], "name" : [ "一条牧羊犬" ], "票房" : [ "34.72亿" ] } } ] }

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 labels 否 Array of strings 实体类型列表。 offset 否 Integer 翻页偏移量，默认为0。 limit 否 Integer 最大返回结果条数，默认为10，最大为100。 conditions 是 conditions object 过滤查询条件。 condition_type 否 String 筛选条件之间的逻辑关系。 缺省值：and 枚举值： and or 表3 conditions 参数 是否必选 参数类型 描述 property_name 否 String 属性名称。 property_value 否 Array of strings 属性值，目前只支持设置一个属性值。

请求消息体 请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。如果请求消息体中参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中username为用户名，domainname为用户所属的账号名称，********为用户登录密码，xxxxxxxxxxxxxxxxxx为project的ID，获取方法请参见获取项目ID。 scope参数定义了Token的作用域，上面示例中获取的Token仅能访问project下的资源。您还可以设置Token作用域为某个账号下所有资源或账号的某个project下的资源，详细定义请参见获取用户Token。 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "id": "xxxxxxxxxxxxxxxxxx" } } } } 到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

请求URI 请求URI由如下部分组成。 {URI-scheme} :// {Endpoint} / {resource-path} ? {query-string} 尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。 URI-scheme：表示用于传输请求的协议，当前所有API均采用HTTPS协议。 Endpoint：指定承载REST服务端点的服务器 域名 或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点中获取终端节点。例如IAM服务在“华北-北京一”区域的Endpoint为“iam.cn-north-1.myhuaweicloud.com”。 resource-path：资源路径，也即API访问路径。从具体API的URI模块获取，例如“获取用户Token”API的resource-path为“/v3/auth/tokens”。 query-string：查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。 例如您需要获取IAM在“华北-北京一”区域的Token，则需使用“华北-北京一”区域的Endpoint（iam.cn-north-1.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。 https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens 图1 URI示意图 为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 如下公共消息头需要添加到请求中。 Content-Type：消息体的类型（格式），必选，默认取值为“application/json”，有其他取值时会在具体接口中专门说明。 X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字段。用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 公有云API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。 AK/SK认证的详细说明请参见AK/SK认证。 X-Project-ID：子项目ID，可选，在多项目场景中使用。 X-Domain-ID：账号ID。 对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求方法 HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。 GET：请求服务器返回指定资源。 PUT：请求服务器更新指定资源。 POST：请求服务器新增资源或执行特殊操作。 DELETE：请求服务器删除指定资源，如删除对象等。 HEAD：请求服务器资源头部。 PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会去创建一个新的资源。 在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为。 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

Token认证 Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。 Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。 Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的Token，即调用获取用户Token接口时，请求body中auth.scope的取值需要选择project，如下所示。 获取用户Token接口请求构造如下，您可以从接口的请求部分看到所需的请求参数及参数说明。 获取Token 消息头只需填写“Content-Type”。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中usernam用户名，domainname为用户所属的账号名称，********为用户登录密码。 获取Token的终端节点和projectname需与KG服务终端节点保持一致。当访问华北-北京四的终端节点（即nlp-ext.cn-north-4.myhuaweicloud.com时），获取Token请使用终端节点https://iam.cn-north-4.myhuaweicloud.com，projectname对应使用cn-north-4。 POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "xxxxxxxx" } } } } 获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token: ABCDEFJ....”加到请求消息头即可，如下所示。 GET https://iam.cn-north-1.myhuaweicloud.com/v3/auth/projects Content-Type: application/json X-Auth-Token: ABCDEFJ.... 您还可以通过视频教程了解如何使用Token认证。

响应示例 状态码： 200 OK { "total" : 2, "entities" : [ { "name" : "不止英雄", "score" : 1, "id" : "6751625866271911141", "label" : "电影", "properties" : { "票房" : "19.50亿" } }, { "name" : "乱世出英雄", "score" : 0.137613, "id" : "4861731593422907967", "label" : "电影", "properties" : { "上映时间" : "1965年1月4日", "票房" : "5.40亿" } } ] } 状态码： 400 Bad Request { "error_code" : "KGP.2001", "error_msg" : "Kg not found" } 状态码： 403 Forbidden { "error_code" : "KGP.0004", "error_msg" : "Auth failed" } 状态码： 500 Internal Server Error { "error_code" : "KGP.9001", "error_msg" : "Internal server error." }

请求示例 搜索不止英雄的票房，返回100条结果 https://nlp-ext.cn-north-4.myhuaweicloud.com/v1/1604d8170cd84440a81281e5a3a04f8b/kg/kg-instances/6cdcea01-bac0-48f6-acb5-9385ea3e24ad/apps/query { "query" : "不止英雄的票房", "limit" : 100 }

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 total Integer 推荐结果个数。 entities KgRecommendRespEntities object 推荐结果详情。 表4 KgRecommendRespEntities 参数 参数类型 描述 id String 推荐的实体节点ID。 name String 推荐的实体节点名称。 score Double 推荐得分，供参考，分值越高说明推荐程度越高。 状态码： 400 表5 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误信息 状态码： 403 表6 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误信息 状态码： 500 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码 error_msg String 错误信息

响应示例 状态码： 200 OK { "total" : 1, "entities" : [ { "id" : "9171851267583370758", "name" : "忆青春", "score" : 42514.35090209614 } ] } 状态码： 400 Bad Request { "error_code" : "KGP.2001", "error_msg" : "Kg not found" } 状态码： 403 Forbidden { "error_code" : "KGP.0004", "error_msg" : "Auth failed" } 状态码： 500 Internal Server Error { "error_code" : "KGP.9001", "error_msg" : "Internal server error." }