Merge pull request #1125 from yyyangw/doc/ScriptsAPI

增加“API调用操作指引文档”

doc/zh/guide/服务端/ScriptAPI_guide.md

@@ -0,0 +1,392 @@
+# API调用脚本使用指引
+
+## 操作步骤
+#### 1. 修改脚本api_invoke.py的内部参数，填写个人令牌mytoken
+#### 2. 部署代码分析服务
+#### 3. 进入项目根目录
+#### 4. 检查requests 模块是否安装，如未安装，可执行下列安装指令。
+```bash
+pip install requests
+```
+#### 5. 执行脚本python ScriptsAPI.py
+#### 6. 设置参数method，选择要执行的api接口，并根据接口添加所需参数。
+
+## 方法总览
+
+| method                 | 类型                  |
+|------------------------|---------------------|
+| create_repository      | 创建代码库               |
+| update_scheme_settings | 设置指定代码库的指定方案的代码度量配置 |
+| create_project         | 创建分析项目              |
+| create_scans           | 启动任务                |
+| get_scan_cons          | 轮询任务结果              |
+| get_overview           | 获取分析概览              |
+| get_issues             | 查看扫描问题列表            |
+| get_issue_detail       | 查看问题详情              |
+| get_ccissues           | 查看指定项目的圈复杂度问题列表     |
+|  get_dupfiles          | 查看指定项目的重复文件列表       |
+
+
+## API详细信息
+
+
+### 一、创建代码库
+#### 1. url请求
+```
+POST /server/main/api/orgs/<org_sid>/teams/<team_name>/repos/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段        | 类型  | 描述                       |
+|-----------|-----|--------------------------|
+| method    | str | 调用的方法名，create_repository |
+| base_url  | str | 基础路径                     |
+| org_sid   | str | 项目组名称                    |
+| team_name | str | 团队唯一标识                   |
+| scm_url   | str | 代码库地址                    |
+|  scm_type | str | 填git或svn                 |
+
+##### 脚本内部参数
+| Key           | 类型  | Value                |
+|---------------|-----|----------------------|
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=create_repository --org_sid=E5BbtAHm2Bh --team_name=project --scm_url=https://github.com/Tencent/CodeAnalysis.git --scm_type=git
+```
+
+#### 4. 结果展示
+![create_repository](../../../images/api_create_repository_response.png)
+
+
+![create_repository](../../../images/api_create_repository_cons.png)
+
+
+### 二、设置指定代码库的指定方案的代码度量配置
+#### 1. url请求
+```
+PUT /server/main/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/schemes/<scheme_id>/metricconf/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段        | 类型  | 描述                       |
+|-----------|-----|--------------------------|
+| method    | str | 调用的方法名，update_scheme_settings |
+| base_url  | str | 基础路径                     |
+| org_sid   | str | 项目组名称                    |
+| team_name | str | 团队唯一标识                   |
+| repo_id   | str | 代码库id                    |
+| scheme_id | str | 扫描方案id                   |
+
+##### 脚本内部参数
+| Key           | 类型  | Value                |
+|---------------|-----|----------------------|
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=update_scheme_settings --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=47 --scheme_id=9
+```
+
+#### 4. 结果展示
+![update_scheme_settings](../../../images/api_update_scheme_settings_response.png)
+
+
+![update_scheme_settings](../../../images/api_update_scheme_settings_cons.png)
+
+
+
+### 三、创建分析项目
+#### 1. url请求
+```
+POST /server/main/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段               | 类型  | 描述                                    |
+|------------------|-----|---------------------------------------|
+| method           | str | 调用的方法名，create_repository              |
+| base_url         | str | 基础路径                                  |
+| org_sid          | str | 项目组名称                                 |
+| team_name        | str | 团队唯一标识                                |
+| repo_id          | str | 代码库id                                 |
+| scan_scheme_id   | int | 和global_scheme_id二选一进行填写，当前代码库的扫描方案编号 |
+| global_scheme_id | int | 和scan_scheme_id二选一进行填写，扫描方案模板编号       |
+| branch           | str | 分支                                    |
+
+
+##### 脚本内部参数
+| Key           | 类型  | Value                |
+|---------------|-----|----------------------|
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=create_project --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=47 --scan_scheme_id=42 --branch=main
+```
+
+#### 4. 结果展示
+![create_project](../../../images/api_create_project_response.png)
+
+
+![create_project](../../../images/api_create_project_cons.png)
+
+
+### 四、启动任务
+#### 1. url请求
+```
+POST /server/main/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/scans/create/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段         | 类型  | 描述                       |
+|------------|-----|--------------------------|
+| method     | str | 调用的方法名，create_scans |
+| base_url   | str | 基础路径                     |
+| org_sid    | str | 项目组名称                    |
+| team_name  | str | 团队唯一标识                   |
+| repo_id    | str | 代码库id                    |
+| project_id | str | 分析项目id                   |
+
+
+##### 脚本内部参数
+| Key           | 类型  | Value                |
+|---------------|-----|----------------------|
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=create_scans --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=47 --project_id=48 
+```
+
+#### 4. 结果展示
+![create_scans](../../../images/api_create_scans_response.png)
+
+
+![create_scans](../../../images/api_create_scans_cons.png)
+
+
+### 五、轮询任务结果
+#### 1. url请求
+```
+GET /server/main/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/jobs/<job_id>/detail/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段         | 类型  | 描述                       |
+|------------|-----|--------------------------|
+| method     | str | 调用的方法名，get_scan_cons |
+| base_url   | str | 基础路径                     |
+| org_sid    | str | 项目组名称                    |
+| team_name  | str | 团队唯一标识                   |
+| repo_id    | str | 代码库id                    |
+| project_id | str | 分析项目id                   |
+
+##### 脚本内部参数
+| Key | 类型   | Value |
+|--|------| - |
+| Authorization | str  | "Token 当前user的token" |
+| sleeptime | int  | 轮询间隔的时间 |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=get_scan_cons --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=47 --project_id=48 --job_id=20
+```
+
+#### 4. 结果展示
+![get_scan_cons](../../../images/api_get_scan_cons_1.png)
+![get_scan_cons](../../../images/api_get_scan_cons_2.png)
+此时分析项目正在执行中，调用访问任务结果的api接口后会不断进行轮询，直到项目执行完毕。
+
+![get_scan_cons](../../../images/api_get_scan_cons_3.png)
+![get_scan_cons](../../../images/api_get_scan_cons_4.png)
+
+如果参数填写出现错误，会给出提示。
+![get_scan_cons](../../../images/api_get_scan_cons_5.png)
+
+
+### 六、获取分析概览
+#### 1. url请求
+```
+GET /server/analysis/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/overview/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段          | 类型  | 描述                  |
+|-------------|-----|---------------------|
+| method      | str | 调用的方法名，get_overview |
+| base_url    | str | 基础路径                |
+| org_sid     | str | 项目组名称               |
+| team_name   | str | 团队唯一标识              |
+| repo_id     | str | 代码库id               |
+| project_id  | str | 分析项目id              |
+
+##### 脚本内部参数
+| Key | 类型  | Value |
+|--|-----| - |
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=get_overview --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=47 --project_id=48
+```
+
+#### 4. 结果展示
+![get_overview](../../../images/api_get_overview_1.png)
+![get_overview](../../../images/api_get_overview_2.png)
+![get_overview](../../../images/api_get_overview_3.png)
+![get_overview](../../../images/api_get_overview_4.png)
+
+
+### 七、查看扫描问题列表
+#### 1. url请求
+```
+GET /server/analysis/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/codelint/issues/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段         | 类型  | 描述                |
+|------------|-----|-------------------|
+| method     | str | 调用的方法名，get_issues |
+| base_url   | str | 基础路径              |
+| org_sid    | str | 项目组名称             |
+| team_name  | str | 团队唯一标识            |
+| repo_id    | str | 代码库id             |
+| project_id | str | 分析项目id            |
+
+##### 脚本内部参数
+| Key | 类型  | Value |
+|--|-----| - |
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=get_issues --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=48 --project_id=49
+```
+
+#### 4. 结果展示
+![get_issues](../../../images/api_get_issues_response.png)
+
+
+![get_issues](../../../images/api_get_issues_cons.png)
+
+
+### 八、查看问题详情
+#### 1. url请求
+```
+GET /server/analysis/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/codelint/issues/<issue_id>/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段         | 类型  | 描述                      |
+|------------|-----|-------------------------|
+| method     | str | 调用的方法名，get_issue_detail |
+| base_url   | str | 基础路径                    |
+| org_sid    | str | 项目组名称                   |
+| team_name  | str | 团队唯一标识                  |
+| repo_id    | str | 代码库id                   |
+| project_id | str | 分析项目id                  |
+|  issue_id  | str | 问题id                    |
+
+##### 脚本内部参数
+| Key | 类型  | Value |
+|--|-----| - |
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=get_issue_detail --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=48 --project_id=49 --issue_id=185
+```
+
+#### 4. 结果展示
+![get_issue_detail](../../../images/api_get_issue_detail_response.png)
+
+
+![get_issue_detail](../../../images/api_get_issue_detail_cons.png)
+
+
+### 九、查看指定项目的圈复杂度问题列表
+#### 1. url请求
+```
+GET /server/analysis/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/codemetric/ccissues/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段         | 类型  | 描述                  |
+|------------|-----|---------------------|
+| method     | str | 调用的方法名，get_ccissues |
+| base_url   | str | 基础路径                |
+| org_sid    | str | 项目组名称               |
+| team_name  | str | 团队唯一标识              |
+| repo_id    | str | 代码库id               |
+| project_id | str | 分析项目id              |
+
+##### 脚本内部参数
+| Key | 类型  | Value |
+|--|-----| - |
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=get_ccissues --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=48 --project_id=49
+```
+
+#### 4. 结果展示
+![get_ccissues](../../../images/api_get_ccissues_response.png)
+
+
+![get_ccissues](../../../images/api_get_ccissues_cons.png)
+
+
+
+### 十、查看指定项目的重复文件列表
+#### 1. url请求
+```
+GET /server/analysis/api/orgs/<org_sid>/teams/<team_name>/repos/<repo_id>/projects/<project_id>/codemetric/dupfiles/
+```
+#### 2. 参数说明
+##### 脚本参数
+
+| 字段         | 类型  | 描述                   |
+|------------|-----|----------------------|
+| method     | str | 调用的方法名，get_dupfiles  |
+| base_url   | str | 基础路径                 |
+| org_sid    | str | 项目组名称                |
+| team_name  | str | 团队唯一标识               |
+| repo_id    | str | 代码库id                |
+| project_id | str | 分析项目id               |
+
+##### 脚本内部参数
+| Key | 类型  | Value |
+|--|-----| - |
+| Authorization | str | "Token 当前user的token" |
+
+#### 3. 操作示例
+```bash
+python ScriptsAPI.py --base_url=http://<my_ip>/ --method=get_dupfiles --org_sid=E5BbtAHm2Bh --team_name=project --repo_id=48 --project_id=49
+```
+
+#### 4. 结果展示
+![get_dupfiles](../../../images/api_get_dupfiles_response.png)
+
+
+![get_dupfiles](../../../images/api_get_dupfiles_cons.png)
+
+
+
+
+
+
+
+
+