azure-devops-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Azure DevOps REST API Skill

Azure DevOps REST API Skill

Comprehensive guide for Azure DevOps REST API v7.2 operations including work items, pipelines, repositories, test plans, wikis, and search functionality.
本指南全面介绍Azure DevOps REST API v7.2的各项操作,包括工作项、流水线、代码库、测试计划、Wiki及搜索功能。

Quick Reference

快速参考

AreaBase URLMCP Tool Prefix
Core
dev.azure.com/{org}/_apis/
mcp__ado__core_*
Work Items
dev.azure.com/{org}/{project}/_apis/wit/
mcp__ado__wit_*
Pipelines
dev.azure.com/{org}/{project}/_apis/pipelines/
mcp__ado__pipelines_*
Git/Repos
dev.azure.com/{org}/{project}/_apis/git/
mcp__ado__repo_*
Test Plans
dev.azure.com/{org}/{project}/_apis/testplan/
mcp__ado__testplan_*
Wiki
dev.azure.com/{org}/{project}/_apis/wiki/
mcp__ado__wiki_*
Search
almsearch.dev.azure.com/{org}/_apis/search/
mcp__ado__search_*
领域Base URLMCP Tool Prefix
核心
dev.azure.com/{org}/_apis/
mcp__ado__core_*
工作项
dev.azure.com/{org}/{project}/_apis/wit/
mcp__ado__wit_*
流水线
dev.azure.com/{org}/{project}/_apis/pipelines/
mcp__ado__pipelines_*
Git/代码库
dev.azure.com/{org}/{project}/_apis/git/
mcp__ado__repo_*
测试计划
dev.azure.com/{org}/{project}/_apis/testplan/
mcp__ado__testplan_*
Wiki
dev.azure.com/{org}/{project}/_apis/wiki/
mcp__ado__wiki_*
搜索
almsearch.dev.azure.com/{org}/_apis/search/
mcp__ado__search_*

Authentication Methods

认证方式

Personal Access Token (PAT)

个人访问令牌(PAT)

bash
undefined
bash
undefined

Base64 encode empty username with PAT

使用PAT对空用户名进行Base64编码

AUTH=$(echo -n ":${PAT}" | base64) curl -H "Authorization: Basic ${AUTH}" https://dev.azure.com/{org}/_apis/projects
undefined
AUTH=$(echo -n ":${PAT}" | base64) curl -H "Authorization: Basic ${AUTH}" https://dev.azure.com/{org}/_apis/projects
undefined

OAuth 2.0 Scopes

OAuth 2.0 权限范围

ScopeAccess Level
vso.work
Read work items
vso.work_write
Create/update work items
vso.code
Read source code
vso.code_write
Create branches, PRs
vso.build_execute
Run pipelines
vso.test
Read test plans
vso.wiki
Read wikis
权限范围访问级别
vso.work
读取工作项
vso.work_write
创建/更新工作项
vso.code
读取源代码
vso.code_write
创建分支、拉取请求(PR)
vso.build_execute
运行流水线
vso.test
读取测试计划
vso.wiki
读取Wiki

API Versioning

API版本控制

Format:
{major}.{minor}[-{stage}[.{resource-version}]]
  • Current:
    7.2-preview.3
  • Example:
    api-version=7.2-preview.3

格式:
{major}.{minor}[-{stage}[.{resource-version}]]
  • 当前版本:
    7.2-preview.3
  • 示例:
    api-version=7.2-preview.3

1. Work Item Operations

1. 工作项操作

Available MCP Tools

可用MCP工具

mcp__ado__wit_get_work_item          - Get single work item
mcp__ado__wit_get_work_items_batch_by_ids - Get multiple work items
mcp__ado__wit_my_work_items          - Get items assigned to me
mcp__ado__wit_create_work_item       - Create new work item
mcp__ado__wit_update_work_item       - Update work item fields
mcp__ado__wit_update_work_items_batch - Bulk update work items
mcp__ado__wit_add_work_item_comment  - Add comment to work item
mcp__ado__wit_list_work_item_comments - List work item comments
mcp__ado__wit_add_child_work_items   - Create child work items
mcp__ado__wit_work_items_link        - Link work items together
mcp__ado__wit_work_item_unlink       - Remove work item links
mcp__ado__wit_link_work_item_to_pull_request - Link to PR
mcp__ado__wit_add_artifact_link      - Add artifact links (branch, commit, build)
mcp__ado__wit_get_work_item_type     - Get work item type definition
mcp__ado__wit_list_backlogs          - List team backlogs
mcp__ado__wit_list_backlog_work_items - Get backlog items
mcp__ado__wit_get_work_items_for_iteration - Get sprint items
mcp__ado__wit_get_query              - Get saved query
mcp__ado__wit_get_query_results_by_id - Execute saved query
mcp__ado__wit_get_work_item          - 获取单个工作项
mcp__ado__wit_get_work_items_batch_by_ids - 批量获取多个工作项
mcp__ado__wit_my_work_items          - 获取分配给我的工作项
mcp__ado__wit_create_work_item       - 创建新工作项
mcp__ado__wit_update_work_item       - 更新工作项字段
mcp__ado__wit_update_work_items_batch - 批量更新工作项
mcp__ado__wit_add_work_item_comment  - 为工作项添加评论
mcp__ado__wit_list_work_item_comments - 列出工作项评论
mcp__ado__wit_add_child_work_items   - 创建子工作项
mcp__ado__wit_work_items_link        - 关联工作项
mcp__ado__wit_work_item_unlink       - 移除工作项关联
mcp__ado__wit_link_work_item_to_pull_request - 关联到拉取请求(PR)
mcp__ado__wit_add_artifact_link      - 添加工件关联(分支、提交、构建)
mcp__ado__wit_get_work_item_type     - 获取工作项类型定义
mcp__ado__wit_list_backlogs          - 列出团队待办事项
mcp__ado__wit_list_backlog_work_items - 获取待办事项工作项
mcp__ado__wit_get_work_items_for_iteration - 获取迭代(冲刺)工作项
mcp__ado__wit_get_query              - 获取已保存的查询
mcp__ado__wit_get_query_results_by_id - 执行已保存的查询

WIQL Query Syntax

WIQL查询语法

Basic Structure

基本结构

sql
SELECT [Fields]
FROM workitems
WHERE [Conditions]
ORDER BY [Fields]
ASOF [DateTime]
sql
SELECT [字段]
FROM workitems
WHERE [条件]
ORDER BY [字段]
ASOF [日期时间]

Common Macros

常用宏

MacroDescription
@Me
Current user
@project
Current project
@Today
Today's date
@Today - N
N days ago
@CurrentIteration
Current sprint
@StartOfMonth
First of month
描述
@Me
当前用户
@project
当前项目
@Today
今日日期
@Today - N
N天前
@CurrentIteration
当前迭代(冲刺)
@StartOfMonth
当月第一天

Example Queries

查询示例

sql
-- Active tasks assigned to me
SELECT [System.Id], [System.Title], [System.State]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Task'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
ORDER BY [System.Priority] ASC

-- Bugs created in last 30 days
SELECT [System.Id], [System.Title], [System.CreatedDate]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Bug'
  AND [System.CreatedDate] >= @Today - 30

-- Parent-child hierarchy
SELECT [Source].[System.Id], [Target].[System.Id]
FROM workitemLinks
WHERE [Source].[System.TeamProject] = @project
  AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
MODE (Recursive)
sql
-- 分配给我的活跃任务
SELECT [System.Id], [System.Title], [System.State]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Task'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
ORDER BY [System.Priority] ASC

-- 过去30天创建的Bug
SELECT [System.Id], [System.Title], [System.CreatedDate]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Bug'
  AND [System.CreatedDate] >= @Today - 30

-- 父子层级
SELECT [Source].[System.Id], [Target].[System.Id]
FROM workitemLinks
WHERE [Source].[System.TeamProject] = @project
  AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
MODE (Recursive)

JSON Patch Operations

JSON Patch操作

json
[
  {"op": "add", "path": "/fields/System.Title", "value": "New Title"},
  {"op": "replace", "path": "/fields/System.State", "value": "Active"},
  {"op": "add", "path": "/relations/-", "value": {
    "rel": "System.LinkTypes.Related",
    "url": "https://dev.azure.com/{org}/_apis/wit/workItems/{id}"
  }}
]
json
[
  {"op": "add", "path": "/fields/System.Title", "value": "New Title"},
  {"op": "replace", "path": "/fields/System.State", "value": "Active"},
  {"op": "add", "path": "/relations/-", "value": {
    "rel": "System.LinkTypes.Related",
    "url": "https://dev.azure.com/{org}/_apis/wit/workItems/{id}"
  }}
]

Link Types Reference

关联类型参考

TypeRel Name
Parent
System.LinkTypes.Hierarchy-Reverse
Child
System.LinkTypes.Hierarchy-Forward
Related
System.LinkTypes.Related
Predecessor
System.LinkTypes.Dependency-Reverse
Successor
System.LinkTypes.Dependency-Forward

类型关联名称
父项
System.LinkTypes.Hierarchy-Reverse
子项
System.LinkTypes.Hierarchy-Forward
相关
System.LinkTypes.Related
前置项
System.LinkTypes.Dependency-Reverse
后置项
System.LinkTypes.Dependency-Forward

2. Pipeline Operations

2. 流水线操作

Available MCP Tools

可用MCP工具

mcp__ado__pipelines_get_build_definitions - List pipeline definitions
mcp__ado__pipelines_get_build_definition_revisions - Get definition history
mcp__ado__pipelines_get_builds         - List builds
mcp__ado__pipelines_get_build_status   - Get build status
mcp__ado__pipelines_get_build_log      - Get build logs
mcp__ado__pipelines_get_build_log_by_id - Get specific log
mcp__ado__pipelines_get_build_changes  - Get commits in build
mcp__ado__pipelines_run_pipeline       - Trigger pipeline run
mcp__ado__pipelines_get_run            - Get pipeline run details
mcp__ado__pipelines_list_runs          - List pipeline runs
mcp__ado__pipelines_update_build_stage - Retry/cancel stage
mcp__ado__pipelines_get_build_definitions - 列出流水线定义
mcp__ado__pipelines_get_build_definition_revisions - 获取定义历史
mcp__ado__pipelines_get_builds         - 列出构建记录
mcp__ado__pipelines_get_build_status   - 获取构建状态
mcp__ado__pipelines_get_build_log      - 获取构建日志
mcp__ado__pipelines_get_build_log_by_id - 获取特定日志
mcp__ado__pipelines_get_build_changes  - 获取构建中的提交记录
mcp__ado__pipelines_run_pipeline       - 触发流水线运行
mcp__ado__pipelines_get_run            - 获取流水线运行详情
mcp__ado__pipelines_list_runs          - 列出流水线运行记录
mcp__ado__pipelines_update_build_stage - 重试/取消阶段

Pipeline Trigger Example

流水线触发示例

json
{
  "resources": {
    "repositories": {
      "self": {"refName": "refs/heads/feature-branch"}
    }
  },
  "templateParameters": {
    "environment": "staging"
  },
  "variables": {
    "customVar": {"value": "custom-value", "isSecret": false}
  }
}
json
{
  "resources": {
    "repositories": {
      "self": {"refName": "refs/heads/feature-branch"}
    }
  },
  "templateParameters": {
    "environment": "staging"
  },
  "variables": {
    "customVar": {"value": "custom-value", "isSecret": false}
  }
}

Build Status Values

构建状态值

StatusDescription
none
Not started
inProgress
Running
completed
Finished
cancelling
Being cancelled
postponed
Delayed
notStarted
Queued
状态描述
none
未开始
inProgress
运行中
completed
已完成
cancelling
正在取消
postponed
已延迟
notStarted
已排队

Build Result Values

构建结果值

ResultDescription
succeeded
All tasks passed
partiallySucceeded
Some tasks failed
failed
Build failed
canceled
User cancelled

结果描述
succeeded
所有任务通过
partiallySucceeded
部分任务失败
failed
构建失败
canceled
用户已取消

3. Repository Operations

3. 代码库操作

Available MCP Tools

可用MCP工具

mcp__ado__repo_list_repos_by_project   - List repositories
mcp__ado__repo_get_repo_by_name_or_id  - Get repository details
mcp__ado__repo_list_branches_by_repo   - List branches
mcp__ado__repo_list_my_branches_by_repo - List my branches
mcp__ado__repo_get_branch_by_name      - Get branch details
mcp__ado__repo_create_branch           - Create new branch
mcp__ado__repo_search_commits          - Search commit history
mcp__ado__repo_list_pull_requests_by_repo_or_project - List PRs
mcp__ado__repo_get_pull_request_by_id  - Get PR details
mcp__ado__repo_create_pull_request     - Create PR
mcp__ado__repo_update_pull_request     - Update PR (autocomplete, status)
mcp__ado__repo_update_pull_request_reviewers - Add/remove reviewers
mcp__ado__repo_list_pull_request_threads - List PR comments
mcp__ado__repo_list_pull_request_thread_comments - Get thread comments
mcp__ado__repo_create_pull_request_thread - Create comment thread
mcp__ado__repo_reply_to_comment        - Reply to comment
mcp__ado__repo_resolve_comment         - Resolve thread
mcp__ado__repo_list_pull_requests_by_commits - Find PR by commit
mcp__ado__repo_list_repos_by_project   - 列出项目下的代码库
mcp__ado__repo_get_repo_by_name_or_id  - 获取代码库详情
mcp__ado__repo_list_branches_by_repo   - 列出代码库分支
mcp__ado__repo_list_my_branches_by_repo - 列出我创建的分支
mcp__ado__repo_get_branch_by_name      - 获取分支详情
mcp__ado__repo_create_branch           - 创建新分支
mcp__ado__repo_search_commits          - 搜索提交历史
mcp__ado__repo_list_pull_requests_by_repo_or_project - 列出拉取请求(PR)
mcp__ado__repo_get_pull_request_by_id  - 获取PR详情
mcp__ado__repo_create_pull_request     - 创建PR
mcp__ado__repo_update_pull_request     - 更新PR(自动完成、状态)
mcp__ado__repo_update_pull_request_reviewers - 添加/移除评审人
mcp__ado__repo_list_pull_request_threads - 列出PR评论线程
mcp__ado__repo_list_pull_request_thread_comments - 获取线程评论
mcp__ado__repo_create_pull_request_thread - 创建评论线程
mcp__ado__repo_reply_to_comment        - 回复评论
mcp__ado__repo_resolve_comment         - 解决评论线程
mcp__ado__repo_list_pull_requests_by_commits - 通过提交记录查找PR

PR Status Values

PR状态值

StatusDescription
active
Open for review
abandoned
Closed without merge
completed
Merged
状态描述
active
开放评审
abandoned
已关闭未合并
completed
已合并

Merge Strategies

合并策略

StrategyDescription
noFastForward
Merge commit (default)
squash
Squash commits
rebase
Rebase and fast-forward
rebaseMerge
Rebase with merge commit

策略描述
noFastForward
合并提交(默认)
squash
压缩提交
rebase
变基并快进
rebaseMerge
变基并创建合并提交

4. Test Plan Operations

4. 测试计划操作

Available MCP Tools

可用MCP工具

mcp__ado__testplan_list_test_plans     - List test plans
mcp__ado__testplan_create_test_plan    - Create test plan
mcp__ado__testplan_create_test_suite   - Create test suite
mcp__ado__testplan_list_test_cases     - List test cases in suite
mcp__ado__testplan_create_test_case    - Create test case
mcp__ado__testplan_update_test_case_steps - Update test steps
mcp__ado__testplan_add_test_cases_to_suite - Add cases to suite
mcp__ado__testplan_show_test_results_from_build_id - Get test results
mcp__ado__testplan_list_test_plans     - 列出测试计划
mcp__ado__testplan_create_test_plan    - 创建测试计划
mcp__ado__testplan_create_test_suite   - 创建测试套件
mcp__ado__testplan_list_test_cases     - 列出测试套件中的测试用例
mcp__ado__testplan_create_test_case    - 创建测试用例
mcp__ado__testplan_update_test_case_steps - 更新测试步骤
mcp__ado__testplan_add_test_cases_to_suite - 将测试用例添加到套件
mcp__ado__testplan_show_test_results_from_build_id - 获取测试结果

Test Case Steps Format

测试用例步骤格式

1. Navigate to login page|Login page displayed
2. Enter username|Username field populated
3. Enter password|Password field populated
4. Click login button|User is logged in successfully
1. 导航至登录页面|登录页面显示
2. 输入用户名|用户名字段已填充
3. 输入密码|密码字段已填充
4. 点击登录按钮|用户成功登录

Test Suite Types

测试套件类型

TypeDescription
staticTestSuite
Manual hierarchy
dynamicTestSuite
Query-based
requirementTestSuite
Linked to requirement
类型描述
staticTestSuite
手动层级结构
dynamicTestSuite
查询驱动型
requirementTestSuite
关联到需求

Test Outcome Values

测试结果值

OutcomeDescription
Passed
Test passed
Failed
Test failed
Blocked
Cannot execute
NotExecuted
Not run
Inconclusive
No clear result

结果描述
Passed
测试通过
Failed
测试失败
Blocked
无法执行
NotExecuted
未运行
Inconclusive
结果不明确

5. Wiki Operations

5. Wiki操作

Available MCP Tools

可用MCP工具

mcp__ado__wiki_list_wikis              - List wikis
mcp__ado__wiki_get_wiki                - Get wiki details
mcp__ado__wiki_list_pages              - List wiki pages
mcp__ado__wiki_get_page                - Get page metadata
mcp__ado__wiki_get_page_content        - Get page content
mcp__ado__wiki_create_or_update_page   - Create/update page
mcp__ado__wiki_list_wikis              - 列出Wiki
mcp__ado__wiki_get_wiki                - 获取Wiki详情
mcp__ado__wiki_list_pages              - 列出Wiki页面
mcp__ado__wiki_get_page                - 获取页面元数据
mcp__ado__wiki_get_page_content        - 获取页面内容
mcp__ado__wiki_create_or_update_page   - 创建/更新页面

Wiki Types

Wiki类型

TypeDescription
projectWiki
Project-scoped wiki
codeWiki
Git-backed wiki
类型描述
projectWiki
项目级Wiki
codeWiki
Git托管的Wiki

Page Path Format

页面路径格式

  • Root:
    /
  • Subpage:
    /Parent/Child
  • Spaces:
    /My%20Page

  • 根路径:
    /
  • 子页面:
    /Parent/Child
  • 含空格:
    /My%20Page

6. Search Operations

6. 搜索操作

Available MCP Tools

可用MCP工具

mcp__ado__search_code                  - Search source code
mcp__ado__search_workitem              - Search work items
mcp__ado__search_wiki                  - Search wiki pages
mcp__ado__search_code                  - 搜索源代码
mcp__ado__search_workitem              - 搜索工作项
mcp__ado__search_wiki                  - 搜索Wiki页面

Code Search Filters

代码搜索过滤器

json
{
  "Project": ["project-name"],
  "Repository": ["repo-name"],
  "Path": ["/src"],
  "Branch": ["main"],
  "CodeElement": ["class", "def", "function"]
}
json
{
  "Project": ["project-name"],
  "Repository": ["repo-name"],
  "Path": ["/src"],
  "Branch": ["main"],
  "CodeElement": ["class", "def", "function"]
}

Work Item Search Filters

工作项搜索过滤器

json
{
  "System.TeamProject": ["project-name"],
  "System.WorkItemType": ["Bug", "Task"],
  "System.State": ["Active", "New"],
  "System.AssignedTo": ["user@domain.com"]
}

json
{
  "System.TeamProject": ["project-name"],
  "System.WorkItemType": ["Bug", "Task"],
  "System.State": ["Active", "New"],
  "System.AssignedTo": ["user@domain.com"]
}

7. Core Operations

7. 核心操作

Available MCP Tools

可用MCP工具

mcp__ado__core_list_projects           - List projects
mcp__ado__core_list_project_teams      - List teams
mcp__ado__core_get_identity_ids        - Get user identity
mcp__ado__work_list_team_iterations    - List iterations
mcp__ado__work_list_iterations         - List all iterations
mcp__ado__work_create_iterations       - Create iterations
mcp__ado__work_assign_iterations       - Assign to team
mcp__ado__work_get_team_capacity       - Get team capacity
mcp__ado__work_update_team_capacity    - Update capacity
mcp__ado__work_get_iteration_capacities - Get iteration capacity

mcp__ado__core_list_projects           - 列出项目
mcp__ado__core_list_project_teams      - 列出项目团队
mcp__ado__core_get_identity_ids        - 获取用户身份
mcp__ado__work_list_team_iterations    - 列出团队迭代
mcp__ado__work_list_iterations         - 列出所有迭代
mcp__ado__work_create_iterations       - 创建迭代
mcp__ado__work_assign_iterations       - 分配迭代给团队
mcp__ado__work_get_team_capacity       - 获取团队容量
mcp__ado__work_update_team_capacity    - 更新团队容量
mcp__ado__work_get_iteration_capacities - 获取迭代容量

8. Advanced Security Operations

8. 高级安全操作

Available MCP Tools

可用MCP工具

mcp__ado__advsec_get_alerts            - Get security alerts
mcp__ado__advsec_get_alert_details     - Get alert details
mcp__ado__advsec_get_alerts            - 获取安全警报
mcp__ado__advsec_get_alert_details     - 获取警报详情

Alert Types

警报类型

TypeDescription
Dependency
Vulnerable dependencies
Secret
Exposed secrets
Code
Code vulnerabilities

类型描述
Dependency
存在漏洞的依赖项
Secret
暴露的密钥
Code
代码漏洞

Rate Limiting

速率限制

TSTU (Throughput Unit) Limits

TSTU(吞吐量单元)限制

  • Anonymous: 200 TSTUs/minute
  • Authenticated: 1200 TSTUs/minute
  • 匿名用户: 200 TSTU/分钟
  • 已认证用户: 1200 TSTU/分钟

Response Headers

响应头

X-RateLimit-Resource: core
X-RateLimit-Delay: 500
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1609459200
Retry-After: 30
X-RateLimit-Resource: core
X-RateLimit-Delay: 500
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1609459200
Retry-After: 30

Handling Rate Limits

处理速率限制

python
import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 30))
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Rate limit exceeded after retries")

python
import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 30))
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Rate limit exceeded after retries")

Error Handling

错误处理

HTTP Status Codes

HTTP状态码

CodeMeaning
200Success
201Created
204No Content (DELETE)
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict (version)
429Rate Limited
500Server Error
状态码含义
200成功
201创建成功
204无内容(DELETE操作)
400请求错误
401未授权
403禁止访问
404未找到
409冲突(版本问题)
429超出速率限制
500服务器错误

Error Response Format

错误响应格式

json
{
  "$id": "1",
  "innerException": null,
  "message": "Error description",
  "typeName": "Microsoft.VisualStudio.Services.WebApi.VssServiceException",
  "typeKey": "VssServiceException",
  "errorCode": 0
}

json
{
  "$id": "1",
  "innerException": null,
  "message": "错误描述",
  "typeName": "Microsoft.VisualStudio.Services.WebApi.VssServiceException",
  "typeKey": "VssServiceException",
  "errorCode": 0
}

Common Field Reference

常用字段参考

System Fields

系统字段

FieldReference Name
ID
System.Id
Title
System.Title
State
System.State
Assigned To
System.AssignedTo
Area Path
System.AreaPath
Iteration Path
System.IterationPath
Work Item Type
System.WorkItemType
Created Date
System.CreatedDate
Changed Date
System.ChangedDate
Tags
System.Tags
Description
System.Description
字段引用名称
ID
System.Id
标题
System.Title
状态
System.State
分配给
System.AssignedTo
区域路径
System.AreaPath
迭代路径
System.IterationPath
工作项类型
System.WorkItemType
创建日期
System.CreatedDate
修改日期
System.ChangedDate
标签
System.Tags
描述
System.Description

Scheduling Fields

排程字段

FieldReference Name
Story Points
Microsoft.VSTS.Scheduling.Effort
Remaining Work
Microsoft.VSTS.Scheduling.RemainingWork
Original Estimate
Microsoft.VSTS.Scheduling.OriginalEstimate
Completed Work
Microsoft.VSTS.Scheduling.CompletedWork

字段引用名称
故事点
Microsoft.VSTS.Scheduling.Effort
剩余工作量
Microsoft.VSTS.Scheduling.RemainingWork
原始估算
Microsoft.VSTS.Scheduling.OriginalEstimate
已完成工作量
Microsoft.VSTS.Scheduling.CompletedWork

Best Practices

最佳实践

1. Use Batch Operations

1. 使用批量操作

  • Use
    mcp__ado__wit_get_work_items_batch_by_ids
    instead of multiple single calls
  • Max 200 items per batch request
  • 使用
    mcp__ado__wit_get_work_items_batch_by_ids
    替代多次单个调用
  • 每个批量请求最多包含200个项

2. Minimize Field Selection

2. 最小化字段选择

  • Only request fields you need:
    fields=System.Id,System.Title,System.State
  • Reduces response size and API load
  • 仅请求所需字段:
    fields=System.Id,System.Title,System.State
  • 减少响应大小和API负载

3. Handle Pagination

3. 处理分页

  • Use
    $top
    and
    $skip
    for large result sets
  • Follow continuation tokens when provided
  • 对大型结果集使用
    $top
    $skip
    参数
  • 当提供续传令牌时,遵循令牌进行分页

4. Version Control

4. 版本控制

  • Use
    test
    operation in JSON Patch for optimistic concurrency
  • Always check
    rev
    field before updates
  • 在JSON Patch中使用
    test
    操作实现乐观并发
  • 更新前始终检查
    rev
    字段

5. Error Recovery

5. 错误恢复

  • Implement exponential backoff for rate limits
  • Log correlation IDs from response headers

  • 为速率限制实现指数退避策略
  • 记录响应头中的关联ID

References

参考资料