-
几乎所有的调用在线服务api的示例都是基于curl的,能否提供基于Python的示例代码?
-
【问题现象描述】【必填】文字交谈功能的聊天记录按照华为api中应保存至ConnectDbagent服务上,华为暂无提交本服务,导致无法保存聊天记录。【日志或错误截图】【可选】//如果有日志或错误截图,请作为附件上传【开发&测试环境信息】【可选】【版本】【可选】//描述您使用的华为产品版本,或从社区下载的资源版本&链接
-
华为云命令行工具 HCloud CLI由华为云专家贵哥个人作品,欢迎大家下载使用并留言反馈意见。华为云命令行工具 CLI(Huawei Cloud CLI)是基于华为云开放 API 建立的管理工具。借助此工具,您可以通过调用华为云开放 API 来管理华为云产品。该命令行工具与华为云开放 API 一一对应,灵活性高且易于扩展。为什么命令行 CLI公有云产品作为一个平台, 主要的用户是 企业IT管理员、企业应用开发者。 Web UI 界面易用, 但操作难以复用、难以保障用户每次操作的顺序的准确性。 而 RESTful API 提供了更强大的功能, 同时门槛也提升了不少。 为了让用户使用熟悉的命令行、Shell 脚本甚至 TCL、Python 这样的动态语言来快速、方便的操作华为云, 提供 华为云命令行 CLI 工具。华为云CLI工具, 基于开放 RESTful API, 无需服务器侧做任何操作, 即可将当期的开放API提供更易用的 CLI。 同时,基于元数据和自动更新, API增加、修改等可快速无感更新 CLI 工具。参考: 华为云 CLI 在命令格式和参数上参考了 阿里云 CLI 和 Google Cloud CLI( https://cloud.google.com/sdk/gcloud/reference/ ), 并吸收华为CC08的MML等能力和架构。特性:HCloud CLI 命令行工具, 基于 GO-lang 开发, 基于元数据驱动+引擎, 采用 YAML、JSON、Handlebar 等, 具备如下特性: 单一可执行文件, 绿色安装, 随便拷贝安装 多操作系统支持, 包括 Linux、Windows、Mac 等 自动更新命令描述。 系统自动从华为主网站更新命令元数据描述每次用户启动会话更新, 压缩传输, 低于 1s 版本更新元数据为 YAML 和 JSON 文件, 安全可靠 可扩展。 您可基于该命令行工具对华为云原生 API 进行封装,扩展出您想要的功能参数校验能力, 如 enum 类型、数字的范围等多种输出格式, 支持 json、table、csv、 value 等多种可自定义的格式。用户指南华为云 CLI 安装指导华为云 CLI 支持华为云 CLI 采用 GO-lang 开发, 只有一个可执行文件, 可以支持几乎所有操作系统, 包括 Windows、Linux 和 Mac OS 等。安装指导直接从网站下载对应操作系统的可执行文件, 并放到 PATH 中合适的目录即可。 如 Linux, 请下载 hcloud , 并放入 /usr/local/bin 目录即可。命令描述文件华为云 CLI 自动从中心网站下载命令描述文件。 命令描述文件为 yaml 和 json 格式的文本文件, 并存放在用户数据目录中。Linux: ~/.hcloud 目录Windows: C:\User\Your Account\AppData\hcloud 目录华为云 CLI 命令描述文件压缩传输, 文件大约不到 100KB。 华为云 CLI 在用户当前会话过期后, 至少三天进行一次检查新版本。华为云 CLI 命令格式与参数指南典型命令格式在华为云 CLI 中, 典型的命令格式如 hcloud ecs start a44e57e8-a37c-4bcc-b388-a98ab0a51867 --verbosity=debug --format="json"。 其中主要分成如下几部分:hcloud , 华为云CLI命令ecs start, 命令组、命令指令a44e57e8-a37c-4bcc-b388-a98ab0a51867, 命令参数, 可能没有, 也可能有许多多, 采用空格分开 --verbosity=debug --format="json" , 全局辅助参数在下面分别进行详细介绍。命令组、命令指令除了几个特别的命令, help、logout 等外, 其它的命令都由两个部分组成: 命令组、命令指令。 命令组一般与服务相关, 如 ecs、vpc、cce、cse 等, 命令指令一般是动作, 如 list、create、delete、start、shutdown 等, 也有时候包含子服务和动作, 如 cluster/list, cluster/create 等。 一般来说, 命令组和命令指令都是小写单词。 详细的命令组、命令指令的列表, 请参见华为云 CLI 命令参考指南, 比较常见的如下:hcloud ecs list hcloud ecs create hcloud ecs start hcloud ecs shutdown hcloud ecs delete hcloud vpc list hcloud vpc create hcloud cce cluster/list hcloud cce cluster/delete hcloud cce cluster/create hcloud cce deployment/list命令参数###参数名称与顺序 在华为云CLI命令参数, 支持多种表达形式:按顺序的写法长名称短名称如下面的三条命令的含义相同:hcloud iam login szfugui Password mydomain hcloud iam login --username=szfugui --password=Password --domain=mydomain hcloud iam login -u=szfugui -p=password -d=mydomain采用名称(无论长名称还是短名称) 时, 参数没有顺序依赖, 可以交换顺序, 不影响命令执行。 无论单值顺序模式, 还是长短名称模式, 都必须是单一字符串。 为了确保参数的正确性, 建议参数包含在 双引号(“”)内, 如: --format="table(id)"。参数默认值部分命令参数有默认值, 请参考各命令的文档。 必填参数如果非 --body 与--source参数时, 部分参数可能是必须输入的, 如果没有输入, 则命令行会提示参数输入不完整。全局辅助参数华为云 CLI 的全局辅助参数, 没有短名称, 也没有序号, 必须采用全名的模式来书写。 如 --verbosity=debug。 与普通命令参数存在此差异。 除此外, 其它要求与普通命令参数一致。全局辅助参数主要有:自定义请求体 body 参数--body="{'id':'自定义请求体'}" 。 在 华为CLI 中, 命令创建者为了简化使用, 抽取了部分参数作为命令行参数, 可以快速实现命令。 但由于参数太多或者不常用, 部分信息采用"默认值",而无法直接修改。 --body参数可以完整控制 RESTful 的请求体。 当 --body参数出现时, 命令本身的命令参数将不再生效, 由body覆盖。自定义请求体 source 参数--source参数与 --body参数非常相似, 唯一的是从磁盘文件中读取, 而不是直接在命令行上输入。 如:hcloud ecs create --source=createvm.json当 --source参数出现时, 命令本身的命令参数将不再生效, 由body覆盖。 如果一个命令同时存在 --body和--source,则--body优先, --source不再生效。输出格式控制 format 参数通用输出格式参数 --format , 在所有的命令都支持该参数。 如未指定该参数, 则 当前共支持:raw 将命令的 RESTful 响应体完整的输出, 不进行任何的处理(只进行友好显示格式化)。json 采用命令定义的友好json输出格式。 具体输出格式通过命令的 metadata 中的 "output/json" 章节定义table 采用表格的形式进行展示。 具体的输出列由命令的 metadata 中的 output/table 章节定义csv 采用文本形式进行展示, 各列之间采用逗号(,)分隔。 第一行是标题行。具体的输出列由命令的 metadata 中的 output/table 章节定义value 只显示值, 一般在脚本/script中常用。 与 csv 相似, 只是没有标题行。具体的输出列由命令的 metadata 中的 output/table 章节定义详细内容, 见 华为云 CLI 输出格式系统输出控制 verbosity--verbosity 控制系统输出,当前支持的级别包括 debug, info, warning, error, critical, none. 比较常用的是 --verbosity=debug, 进行命令调试, 可以观察到系统内部的大量临时数据、网络传输数据等。长任务等待控制 wait--wait=true 或者 --wait=false 命令控制长事务操作的结果。 例如创建虚拟机等需要较长时间, --wait=true 将查询创建VM 的 job 是否完成, 等待完成后才返回。 不同的任务的操作时长不相同, 有部分命令很快就执行完成, 但有的命令, 如创建 CCE Cluster 则可能需要超过10分钟。helpusage: Display detailed helpparam: versionusage: Print version information and exit华为云 CLI 输出格式使用说明命令指引通用输出格式参数 --format , 在所有的命令都支持该参数。 如未指定该参数, 则 当前共支持:raw 将命令的 RESTful 响应体完整的输出, 不进行任何的处理(只进行友好显示格式化)。json 采用命令定义的友好json输出格式。 具体输出格式通过命令的 metadata 中的 "output/json" 章节定义table 采用表格的形式进行展示。 具体的输出列由命令的 metadata 中的 output/table 章节定csv 采用文本形式进行展示, 各列之间采用逗号(,)分隔。 第一行是标题行。具体的输出列由命令的 metadata 中的 output/table 章节定义value 只显示值, 一般在脚本/script中常用。 与 csv 相似, 只是没有标题行。具体的输出列由命令的 metadata 中的 output/table 章节定义原生格式 raw--format=raw, 不支持任何其它参数。 Raw 原生格式不需要任何参数与配置, 直接将 RESTful API 的输出 BODY 进行 JSON 格式化后, 进行展示。 JSON 格式--format=json, 不支持任何其它参数。 Json 格式是经过命令开发人员手工优化的输出, 其定义在命令定义文件的 output/json 章节。 采用 Handerbar 模板, 对原生的数据(包括各种内部数据、输入输出数据等)进行聚合、优化、整合等, 进行友好展示结果。TABLE表格格式--format=table, 可以不带参数, 也可以对展示列进行指定。 表格格式采用类似文本表格的模式, 对输出数据进行二维展示。 hcloud ecs list --format=table ┌─────┬────────────────┬─────────────────┬────────────────────────┬───────┐ │Index│ Id │ Name │ IP Address │Status │ ├─────┼────────────────┼─────────────────┼────────────────────────┼───────┤ │ 1│73ac0862-09f8...│crc-cluster-15536│192.168.0.10|49.4.87.246│ACTIVE │ │ 2│a44e57e8-a37c...│abchow-docker │192.168.0.128 │SHUTOFF│ └─────┴────────────────┴─────────────────┴────────────────────────┴───────┘表格中“列”的定义, 在 output/table 中进行定义。 支持指定最大宽度、Label、数据来源、对齐模式(默认左对齐,支持居中对齐、右对齐)等。根据需要, 可以只显示其中的一列或者几列, 可以指定需要显示的列, 采用 --format="table(col1,col2,col3)" 的格式进行指定, 如:hcloud ecs list --format="table(index,id,name,status)" ┌─────┬────────────────────────────────────┬─────────────────┬───────┐ │Index│ Id │ Name │Status │ ├─────┼────────────────────────────────────┼─────────────────┼───────┤ │ 1│73ac0862-09f8-4912-af76-04052ef42f74│crc-cluster-15536│ACTIVE │ │ 2│a44e57e8-a37c-4bcc-b388-a98ab0a51867│abchow-docker │SHUTOFF│ └─────┴────────────────────────────────────┴─────────────────┴───────┘有指定列的时候, 配置中指定的“最大宽度”不发生作用, 将字符串的全部数据展示出来, 以满足用户的完整需求。CSV 文本格式--format=csv, 可以不带参数--format=csv(col1,col2,col3), 也可以对展示列进行指定。 CSV文本模式时, 采用逗号(,)对标题和值进行分隔, 便于其它脚本script对输出进行处理。 命令示例如下:hcloud ecs list --format="csv(index,id,name,status)" Index,Id,Name,Status 1,73ac0862-09f8-4912-af76-04052ef42f74,crc-cluster-15536,ACTIVE 2,a44e57e8-a37c-4bcc-b388-a98ab0a51867,abchow-docker,SHUTOFFVALUE 纯值格式--format=value, 可以不带参数--format=value(col1,col2,col3), 也可以对展示列进行指定。 VALUE文本模式时,如果有多列, 采用逗号(,)对进行分隔, 便于其它脚本script对输出进行处理。 命令示例如下:hcloud ecs list --format="csv(index,id,name,status)" 1,73ac0862-09f8-4912-af76-04052ef42f74,crc-cluster-15536,ACTIVE 2,a44e57e8-a37c-4bcc-b388-a98ab0a51867,abchow-docker,SHUTOFF如果只有单列:hcloud ecs list --format="value(id)" 73ac0862-09f8-4912-af76-04052ef42f74 a44e57e8-a37c-4bcc-b388-a98ab0a51867最佳实践虚拟机域名访问全流程用户登录系统hcloud iam login 用户名 密码 { "result": "201 Created", "expires_at": "2019-02-08T15:04:19.073000Z" }如果是子账号登录hcloud iam login 子账号 密码 域名称/主账号 { "result": "201 Created", "expires_at": "2019-02-08T15:06:09.017000Z" }查询当前虚拟机情况hcloud ecs list --format=table ┌─────┬────────────────┬─────────────────┬────────────────────────┬───────┐ │Index│ Id │ Name │ IP Address │Status │ ├─────┼────────────────┼─────────────────┼────────────────────────┼───────┤ │ 1│73ac0862-09f8...│crc-cluster-15536│192.168.0.10|49.4.87.246│SHUTOFF│ │ 2│a44e57e8-a37c...│abchow-docker │192.168.0.128 │SHUTOFF│ └─────┴────────────────┴─────────────────┴────────────────────────┴───────┘当前磁盘镜像查询hcloud ims list --id=a347c189-4d3a-4096-bd72-0ad2be959470 --format=table ┌─────┬────────────────────────────────────┬─────────────────────────┬───────┬───────┬────────┬──────┐ │Index│ Id │ Name │OS Type│Min_ram│Min_disk│Status│ ├─────┼────────────────────────────────────┼─────────────────────────┼───────┼───────┼────────┼──────┤ │ 1│a347c189-4d3a-4096-bd72-0ad2be959470│Ubuntu 18.04 server 64bit│Linux │1024 │40 │active│ └─────┴────────────────────────────────────┴─────────────────────────┴───────┴───────┴────────┴──────┘获取当前存在的VPC和子网hcloud vpc list --format=table ┌────────────────────────────────────┬────────┬──────────────┬──────┐ │ Id │ Name │ Cidr │Status│ ├────────────────────────────────────┼────────┼──────────────┼──────┤ │1f30f26a-f6cd-4626-bf41-da4864529616│ │192.168.0.0/16│OK │ │2d203648-d1cd-4782-a083-0d5323f8ca72│ │192.168.0.0/16│OK │ │45825956-13e0-4e04-9364-606f94ce3011│ │192.168.0.0/16│OK │ │4a0ff926-978b-4dae-be68-37640d513a1c│ │192.168.0.0/16│OK │ │4c3de781-6762-405c-a802-05f2e8c1fdcc│vpc-paas│192.168.0.0/16│OK │ │5066abd7-5c81-4298-9772-3fad6ddd90a3│myvpc │172.20.0.0/16 │OK │ │5c4d190b-55d6-4f70-822e-fc76ac31266a│ │192.168.0.0/16│OK │ │842c2ab8-0326-48be-97ac-f5a14b809f9e│ │192.168.0.0/16│OK │ │87eeadef-2716-4e51-a81b-8e7a5d2be023│ │192.168.0.0/16│OK │ │995bd92b-e1e2-40b3-a7bd-03e97c9b0560│ │192.168.0.0/16│OK │ │99b0eec9-565f-4f41-a52a-a21263d1c235│ │192.168.0.0/16│OK │ │9d1b88bc-5f94-445d-9fc3-c5a66332d4d9│ │192.168.0.0/16│OK │ │b7b6eb7e-19e5-47d2-ab8b-0e2fb6dc33a9│ │192.168.0.0/16│OK │ │c813be70-48f2-4d89-9153-4b4832a875e0│ │192.168.0.0/16│OK │ │f8f4dc7d-4784-487c-a079-eafa3d5cfed8│ │192.168.0.0/16│OK │ │fbf6db89-32a4-415a-885b-a54e08b0384f│ │192.168.0.0/16│OK │ └────────────────────────────────────┴────────┴──────────────┴──────┘获取 VPC 下的子网hcloud vpc subnet/list --format=table ┌────────────────────────────────────┬───────────┬────────────────────────────────────┬───────────────┬────────────┬────┬──────┐ │ Id │ Name │ VPC │ Cidr │ Gateway │DHCP│Status│ ├────────────────────────────────────┼───────────┼────────────────────────────────────┼───────────────┼────────────┼────┼──────┤ │18214a77-c396-409a-b181-8d0b240f4a0b│subnet1 │1f30f26a-f6cd-4626-bf41-da4864529616│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │1dbd8f82-15ab-4f5d-8937-b1a1dc0d1b61│subnet1 │45825956-13e0-4e04-9364-606f94ce3011│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │26cfab59-10e6-4503-be50-aec829820109│subnet1 │fbf6db89-32a4-415a-885b-a54e08b0384f│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │2aa5d37e-205c-4256-920f-951f514dc522│subnet1 │995bd92b-e1e2-40b3-a7bd-03e97c9b0560│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │3cdfa0d0-c39c-4a6a-a4f8-926744e572c2│subnet1 │5c4d190b-55d6-4f70-822e-fc76ac31266a│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │423b253a-d5f3-4915-8990-2d2c302b68c6│mysubnet │5066abd7-5c81-4298-9772-3fad6ddd90a3│172.20.1.0/24 │172.20.1.1 │true│ACTIVE│ │4d62391d-e6f9-435e-8fba-8a2e3682f03c│subnet1 │87eeadef-2716-4e51-a81b-8e7a5d2be023│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │6cbfe2f6-36a1-46d7-beef-19ae0e4b3351│subnet1 │b7b6eb7e-19e5-47d2-ab8b-0e2fb6dc33a9│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │7446c808-68df-4e6d-9f80-b5b1a86d049f│subnet1 │4a0ff926-978b-4dae-be68-37640d513a1c│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │7**5d85-94ae-4f7b-8833-d31eaf62e827│subnet1 │3413fe9e-83bf-4a9b-b020-c8999adc89cb│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │889e7f27-231a-4bf6-a3cf-8339e6746ba5│subnet1 │c813be70-48f2-4d89-9153-4b4832a875e0│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │9dfcb3e7-9be9-464d-8f53-fe42787beb94│subnet1 │2d203648-d1cd-4782-a083-0d5323f8ca72│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │c9f75b54-078d-4cdc-b31f-0e9d9f30a837│subnet1 │56284d2a-518e-4800-85bb-2cd3dacad53e│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │cc00a4f0-ca72-4119-a6be-9012f6c2ac6a│subnet-paas│4c3de781-6762-405c-a802-05f2e8c1fdcc│192.168.0.0/24 │192.168.0.1 │true│ACTIVE│ │d0834208-0025-46c0-bc45-9c9345b1d065│subnet1 │f8f4dc7d-4784-487c-a079-eafa3d5cfed8│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │e2926843-60d0-4d43-ac47-a9e48fb255d7│subnet1 │9d1b88bc-5f94-445d-9fc3-c5a66332d4d9│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │e3192175-096f-4343-b4ae-e473f1c50a1b│subnet1 │99b0eec9-565f-4f41-a52a-a21263d1c235│192.168.20.0/24│192.168.20.1│true│ACTIVE│ │f8576dc0-0ef2-4603-8dcf-f0eec6e7bd65│subnet1 │842c2ab8-0326-48be-97ac-f5a14b809f9e│192.168.20.0/24│192.168.20.1│true│ACTIVE│ └────────────────────────────────────┴───────────┴────────────────────────────────────┴───────────────┴────────────┴────┴──────┘查询指定 VPC 下的子网列表hcloud vpc subnet/list 4c3de781-6762-405c-a802-05f2e8c1fdcc --format=table ┌────────────────────────────────────┬───────────┬────────────────────────────────────┬──────────────┬───────────┬────┬──────┐ │ Id │ Name │ VPC │ Cidr │ Gateway │DHCP│Status│ ├────────────────────────────────────┼───────────┼────────────────────────────────────┼──────────────┼───────────┼────┼──────┤ │cc00a4f0-ca72-4119-a6be-9012f6c2ac6a│subnet-paas│4c3de781-6762-405c-a802-05f2e8c1fdcc│192.168.0.0/24│192.168.0.1│true│ACTIVE│ └────────────────────────────────────┴───────────┴────────────────────────────────────┴──────────────┴───────────┴────┴──────┘创建一个VMhcloud ecs create myvm --image=a347c189-4d3a-4096-bd72-0ad2be959470 --vpc=4c3de781-6762-405c-a802-05f2e8c1fdcc --subnet=cc00a4f0-ca72-4119-a6be-9012f6c2ac6a { "begin_time" : "2019-02-07T21:37:10.619Z", "end_time" : "2019-02-07T21:38:15.807Z", "error_code" : null, "fail_reason" : null, "status" : "SUCCESS", "entities" : { "sub_jobs_total" : 1, "sub_jobs" : [ { "job_id" : "8aace0c6689a2a300168c9e4a26d2313", "job_type" : "createSingleServer", "begin_time" : "2019-02-07T21:37:10.765Z", "end_time" : "2019-02-07T21:38:09.710Z", "error_code" : null, "fail_reason" : null, "status" : "SUCCESS", "entities" : { "server_id" : "a8077071-1e1e-4ef2-bcf2-ec9b3adf6e09" } } ] }, "job_id" : "8aace0c6689a2a300168c9e4a1dc2310", "job_type" : "createServer" }检查VM创建情况:hcloud ecs list --format=table ┌─────┬────────────────────────────────────┬─────────────────┬────────────────────────┬───────┐ │Index│ Id │ Name │ IP Address │Status │ ├─────┼────────────────────────────────────┼─────────────────┼────────────────────────┼───────┤ │ 1│a8077071-1e1e-4ef2-bcf2-ec9b3adf6e09│myvm │192.168.0.129 │ACTIVE │ │ 2│73ac0862-09f8-4912-af76-04052ef42f74│crc-cluster-15536│192.168.0.10|49.4.87.246│ACTIVE │ │ 3│a44e57e8-a37c-4bcc-b388-a98ab0a51867│abchow-docker │192.168.0.128 │SHUTOFF│ └─────┴────────────────────────────────────┴─────────────────┴────────────────────────┴───────┘使用完成后停机并删除该VMhcloud ecs shutdown a8077071-1e1e-4ef2-bcf2-ec9b3adf6e09 hcloud ecs delete a8077071-1e1e-4ef2-bcf2-ec9b3adf6e09 hcloud ecs list --format=table ┌─────┬────────────────────────────────────┬─────────────────┬────────────────────────┬───────┐ │Index│ Id │ Name │ IP Address │Status │ ├─────┼────────────────────────────────────┼─────────────────┼────────────────────────┼───────┤ │ 1│73ac0862-09f8-4912-af76-04052ef42f74│crc-cluster-15536│192.168.0.10|49.4.87.246│ACTIVE │ │ 2│a44e57e8-a37c-4bcc-b388-a98ab0a51867│abchow-docker │192.168.0.128 │SHUTOFF│ └─────┴────────────────────────────────────┴─────────────────┴────────────────────────┴───────┘
-
接口文档: 传送Client专线业务发放API参考.zip 开发指南: 传送Client专线业务发放开发指南.zip SDK:Transport_Client_Services_SDK.zipOptical_Network_Resource_Management_SDK.zip示例:Transport Client Servicesz_Demo.zip
-
开发指南: 传送Client专线业务发放开发指南.zip 接口文档: 传送Client专线业务发放API参考.zip SDK: Optical_Network_Resource_Management_SDK.zipTransport_Client_Services_SDK.zip示例:Transport Client Servicesz_Demo.zip
-
开发指南:传送Client专线业务发放开发指南.zip接口文档:传送Client专线业务发放API参考.zipSDK:Optical_Network_Resource_Management_SDK.zipTransport_Client_Services_SDK.zip示例:Transport Client Servicesz_Demo.zip
-
开发指南: IP专线业务发放开发指南.zip 接口文档:IP网络资源可视和管理API参考.zipIP专线业务发放API参考.zipSDK:IP_Network_Resource_Management.zipIP_Leased_Line_Services.rar
-
发现了一个云化企业专线业务发放API调测的bug,服不服?
-
有时候,软件开发人员想要的是自己的软件被其他应用软件所应用,而不是让人来操作。API使各种应用软件互相通信成为了可能。从事API文档写作15年,我亲眼见证了API产品的崛起。各个公司开始搭建平台,希望别人接入平台并使用平台提供的API。API的发展意味着API文档的增多,这对技术文档工程师无疑是一件好事。 在本文中,我会阐述什么是API,API文档应当包含什么,该类型的AP文档面向哪些读者,以及如何在这个领域快速入门。什么是API?有时候,软件开发人员想要让自己的软件被其他应用软件所应用,而不是让具体的人来使用。因此互动就是和其他软件之间的,而不是一个人,所以就需要达成一个约定的方式去互动。这种语言,和其内在的一系列规则就被称作应用程序编程接口(API)。基本上,API使各种应用软件互相通信成为了可能。你的软件与API之间的信息交换经常表现为一个请求和一个回应的形式。你的软件用API发出一个请求,另一个程序则通过API返回响应。有的API被用来在产品和外来产品之间交换数据。如果你想与Google 或Twitter交互,你可以参考他们的API来写代码,从而在你的产品和他们的产品之间进行数据交换。 有的API被用来在一个公司内部或者一个产品之间进行内在数据交换。Windows和Android操作系统都有内嵌API,以便开发人员编写出可以让系统中不同模块互相通信的子程序。还有的API被用与内部以及外部的交流。亚马逊网站服务中有40多个服务都有给任何人使用的API。亚马逊开发人员也会自己使用这些API,使各种服务之间可以互相通信。不管是被内部还是外部使用,API都需要形成文档,以确保产生通信。什么是API文档?API根据语言和功能的不同而有多样化地形式,但是它们都有一个共性:用户发出一个请求,API(有时候)返回一个响应。技术文档工程师的任务就是详细描述请求包含什么,请求的形式是什么,以及返回的数据是什么。API文档的结构虽然多种多样,但是我认为一份好的API文档需要给读者展示:•操作的语法•操作具体可以干什么•操作涉及哪些变量,包括系统设定值,有效值,以及数据类型--布尔值、字符串,等等•操作的返回值是什么•操作可能会遇到的报错信息•请求和响应的举例 这些听起来很多,但是所有优秀的代码都包含这些内容。API文档工程师需要做的就是去查看,询问,以及像一个编辑一样去识别和减少代码里没有的内容。就核心而言,API文档细化了代码里面的内容:可用的命令,命令的作用,以及各个命令的变量。传统来说,API文档描述了一个操作以及如何发出一个请求。一般是由包含参数名称及参数取值的表格和代码样例组成。一个功能一个API文档,将所有文档组合,就是一份API参考指南。很基础,但很有用。但是针对那些不单是发出一个简单请求的API文档应当怎么写?大多数开发人员想知道API是如何把各个命令串到一起,以及如何在输入和输出间互动。针对这一点,很多文档工程师编写了开发指南,包含API的常见使用场景案例和任务,以及代码样例。另一种形式的API文档,叫做“用户指南”,内容跟代码不相关,倾向于解释API的相关命令行界面或图形用户界面。“用户指南”通常包含了用来辅助理解API的概念、安装部署、配置任务、以及最佳范例。如果文档工程师想要降低API的使用难度——从根本上帮助任何一个有电脑的人使用API—他/她将会开发一个“快速入门指南”。这类文档通过执行一系列任务引导用户理解API,加深对API操作和后续任务的了解。一些公司会把上述各类API相关文档打包,以软件开发工具包(SDK)的形式发布。使用SDK的人们通常希望里面包含的不只是API文档。通畅情况下SDK应当包括代码,测试平台和文档。基本上,API文档的读者都关注这两个方面:正确的信息和可执行的代码样例。谁会使用API文档?在技术沟通交流中,我们经常会把读者分为三大类:终端用户、系统管理员、开发人员。我开始相信,无论是哪种文档,每个读者都只是一个某种意义的终端用户。一些终端用户想要知道如何在应用中创建新文件。一些终端用户想要知道如何在一个终端或命令提示运行一个命令。还有一些终端用户想要知道如何开发和其他程序交换数据的程序。API文档的终端用户通常是开发人员,但是也有一些针对系统管理员的API文档。系统管理员通常查看API文档是为了运行不需要编程的但必须在基础应用上运行的任务。传统来说,这是和命令行操作一起的。比如,为了在一个账户中创建一个用户,系统管理员会执行一个命令来生成一个密匙,这样用户就可以开始对API发出请求。 另一方面,开发人员,或许想创建一系列可以在特定时间、特定场景下下以编程方式运行的操作。例如,当一个请求被返回,第二条命令会用第一条命令的返回值运行。在这种情况下,开发人员就要创建一个使用API功能的工作流或框架。 一些API是针对特殊命令,比如,“这一刻及时备份我的数据库”。一些是以重复性和编程性的方式被使用,比如,“当我的网页服务器达到80%忙碌时,创建另一个网页服务器,在两个服务器中分担负载”。谁来编写API文档?在这个日益发展的行业中写作API文档的人通常被称作“程序文档工程师”或者“高级技术文档工程师”。通常有两条路可以成为一名编写API文档的工程师。第一条路是指那些有很长时间写作经验,擅长沟通实践,并且决定开始写作API文档的人。这一条路叫做“边写作边学习代码”。第二条路是指那些决定致力于写作的开发人员。这条路叫做“边写代码边学习写作”。是一条边开发边学写作的路。本文针对走第一条路的探路者。如果你对API文档写作感兴趣,遵循下面这几条方法,你将受益匪浅:•学习读懂代码。意思是读懂代码,不是必须会写。通过各种途径查看阅读代码里的注释,尝试理解代码的含义。写作API文档需要对一种编程语言有基本了解,不一定要成为一个开发人员。当然,你应当要知道看如何看代码。大体上,你需要理解这个代码是干什么、它为什么被开发、预期目的是什么、以及谁会在什么情况下使用它。•学习API技术常识。正常来说,API信息内容要么用可扩展标示语言(XML),要么用对象表示法(JSON),每一个文件格式都比较容易理解。但是在仍然建议通过入门书去了解了解。当API通过表述性状态转移(REST),或是采用简单对象访问协议(SOAP)开发,你可以通过一本好书或者Google搜索就可以学到这些。•查阅不同的API文档。查看已有的总是好事,例如亚马逊弹性计算云文档:(https://aws.amazon.com/documentation/ec2/),谷歌云存储XML API:(https://developers.google.com/storage/docs/xml-api-overview),还有Twitter的API文档:(https://dev.twitter.com/docs/api)。• 保持谦逊。向专家讨教代码疑问,最好的开发人员有时都会去向别人咨询一些代码上的疑问。如果他们都会如此,文档工程师也不可能全都清楚。但是要记住了:一定要事先准备一下,不要因为自己没有先调查清楚,浪费开发人员的时间。•增长你的好奇心。如果API有工具包或者测试桩,试着用代码玩一玩。使用API发出一个请求,看会发生什么。听起来有好多工作要做,好多东西要学习,但是你只要开始,会发现也就小菜一碟。API文档是一个正在发展的领域。建议你亲自尝试,看自己是否感兴趣。我们需要更多优秀的文档工程师。
-
使用vpc的endpoint调用“查询安全组列表”的API,提示“API not found”,请问啥原因?
推荐直播
-
华为云IoT开源专家实践分享:开源让物联网平台更开放、易用
2024/05/14 周二 16:30-18:00
张俭 华为云IoT DTSE技术布道师
开源,意味着开放、共享、互助、共赢。作为万物上云及各行业数字化的物联网底座,华为云IoT积极拥抱开源,借助行业开源的最佳实践,构建可靠、易用的物联网平台,并通过开放南北向SDK,助力开发者快速构建物联网应用。本期直播,华为云IoT开源专家、物联网平台资深“程序猿”张俭,带你了解华为云IoT的开源生态,并手把手教你玩转开源社区!
去报名 -
企业级数仓迁移工具助您轻松上云
2024/05/21 周二 16:30-18:00
Nick 华为云数仓GaussDB(DWS)研发专家
随着云时代的到来,传统数仓已无法满足企业的需求,越来越多的企业选择从传统数仓迁移到云数据仓库,云数仓为企业提供了更低的成本、更灵活极致的体验。本期直播将为您带来企业级数仓搬迁的解决方案,带您一览华为云数仓GaussDB(DWS)提供了哪些迁移方案助力用户实现数据迁移,如何保障迁移后数据的一致性。
去报名 -
华为云开发者日·广州站
2024/05/23 周四 14:30-17:30
华为云专家团
华为云开发者日HDC.Cloud Day是面向全球开发者的旗舰活动,汇聚来自千行百业、高校及科研院所的开发人员。致力于打造开发者专属的技术盛宴,全方位服务与赋能开发者围绕华为云生态“知、学、用、创、商”的成长路径。通过前沿的技术分享、场景化的动手体验、优秀的应用创新推介,为开发者提供沉浸式学习与交流平台。开放创新,与开发者共创、共享、共赢未来。
去报名
热门标签