Version control items

บทความ
08/04/2016

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 1.0

Items are the files and folders in Team Foundation version control.

If you haven't already, look at the information on getting started with these APIs.

Get a file

GET https://{instance}/DefaultCollection/_apis/tfvc/items/{path}?api-version={version}

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
path	string	Path to the file in TFVC. `$/Fabrikam-Fiber-TFVC/WebSite/WebSite/Views/Home/_Home.cshtml`
Query
api-version	string	Version of the API to use.

When you specify the path of file in the URL, the response contains the contents of the file. You can also get a specific version of an item.

Using path as query parameter

The path can be specified as a query parameter as well.
This format should be used for certain files (like web.config) that are not accessible by using the path as part of the URL due to the default ASP .NET protection.

Request

GET http://fabrikam-fiber-inc:8080/DefaultCollection/_apis/tfvc/items?path=$/Fabrikam-Fiber-TFVC/WebSite/WebSite/web.config&api-version={version}

Response

Status code: 200

<?xml version="1.0"?>
<configuration>
    <system.web>
      <compilation debug="true" targetFramework="4.5.2" />
      <httpRuntime targetFramework="4.5.2" />
    </system.web>
</configuration>

Request

GET http://fabrikam-fiber-inc:8080/DefaultCollection/_apis/tfvc/items/$/Fabrikam-Fiber-TFVC/WebSite/WebSite/Views/Home/_Home.cshtml?api-version={version}

Response

Status code: 200

<div class="jumbotron">
    <h1>ASP.NET</h1>
    <p class="lead">ASP.NET is a free web framework for building great Web sites and Web applications using HTML, CSS, and JavaScript.</p>
    <p><a href="https://asp.net" class="btn btn-primary btn-large">Learn more &raquo;</a></p>
</div>
<div class="row">
    <div class="col-md-4">
        <h2>Getting started</h2>
        <p>
            ASP.NET Single Page Application (SPA) helps you build applications that include significant client-side interactions using HTML, CSS, and JavaScript.
            It's now easier than ever before to getting started writing highly interactive web applications.
        </p>
        <p><a class="btn btn-default" href="https://go.microsoft.com/fwlink/?LinkId=273732">Learn more &raquo;</a></p>
    </div>
    <div class="col-md-4">
        <h2>Get more libraries</h2>
        <p>NuGet is a free Visual Studio extension that makes it easy to add, remove, and update libraries and tools in Visual Studio projects.</p>
        <p><a class="btn btn-default" href="https://go.microsoft.com/fwlink/?LinkId=301866">Learn more &raquo;</a></p>
    </div>
    <div class="col-md-4">
        <h2>Web Hosting</h2>
        <p>You can easily find a web hosting company that offers the right mix of features and price for your applications.</p>
        <p><a class="btn btn-default" href="https://go.microsoft.com/fwlink/?LinkId=301867">Learn more &raquo;</a></p>
    </div>
</div>

Get item metadata for

A file

Specify the path to the file using the scopePath parameter to get the metadata for that file, or for a specific version of the file.

Sample request

GET https://{instance}/DefaultCollection/_apis/tfvc/items?scopePath=/$/Fabrikam-Fiber-inc/AuthSample/AuthSample.sln?api-version={version}

Response

Status code: 200

{
  "count": 1,
  "value": [
    {
      "version": 5,
      "changeDate": "2014-03-19T17:23:59.697Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln"
    }
  ]
}

A folder

Sample request

GET https://mytfsserver/DefaultCollection/_apis/tfvc/items?scopePath=$/Fabrikam-Fiber-TFVC/AuthSample&api-version=1.0-preview.1

Sample response

{
  "value": [
    {
      "version": 5,
      "isBranch": true,
      "changeDate": "2014-03-19T17:23:59.697Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample",
      "isFolder": true,
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample?versionType=Changeset&version=5"
    },
    {
      "version": 9,
      "changeDate": "2014-03-21T19:32:02.213Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln",
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln?versionType=Changeset&version=9"
    },
    {
      "version": 5,
      "changeDate": "2014-03-19T17:23:59.697Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.vssscc",
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.vssscc?versionType=Changeset&version=5"
    },
    {
      "version": 9,
      "changeDate": "2014-03-21T19:32:02.213Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code",
      "isFolder": true,
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code?versionType=Changeset&version=9"
    }
  ],
  "count": 4
}

You can get the metadata for a specific version of a folder, too.

A folder and its children

Use recursionLevel to include the contents of the folder in the response. You can get the contents of a specific version of the folder, too.

Sample request

GET https://mytfsserver/DefaultCollection/_apis/tfvc/items?scopePath=$/Fabrikam-Fiber-TFVC/AuthSample&recursionLevel=OneLevel&api-version=1.0-preview.1

Sample response

{
  "value": [
    {
      "version": 5,
      "isBranch": true,
      "changeDate": "2014-03-19T17:23:59.697Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample",
      "isFolder": true,
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample?versionType=Changeset&version=5"
    },
    {
      "version": 9,
      "changeDate": "2014-03-21T19:32:02.213Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln",
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln?versionType=Changeset&version=9"
    },
    {
      "version": 5,
      "changeDate": "2014-03-19T17:23:59.697Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.vssscc",
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.vssscc?versionType=Changeset&version=5"
    },
    {
      "version": 9,
      "changeDate": "2014-03-21T19:32:02.213Z",
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code",
      "isFolder": true,
      "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code?versionType=Changeset&version=9"
    }
  ],
  "count": 4
}

Multiple items

To get more than one item in a single batch, specify the path of each item in an array of item descriptors in the post body. You can specify the version and recursion level for each item, too.

Sample request

POST https://mytfsserver/DefaultCollection/_apis/tfvc/itemBatch?api-version=1.0-preview.1

{
  "itemDescriptors": [
    {
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample/Program.cs",
      "version": 5,
      "versionType": "changeset"
    },
    {
      "path": "$/Fabrikam-Fiber-TFVC/AuthSample",
      "recursionLevel": "Full"
    }
  ]
}

Sample response

{
  "count": 2,
  "value": [
    [
      {
        "version": 5,
        "changeDate": "2014-03-19T17:23:59.697Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample/Program.cs",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample/Program.cs?versionType=Changeset&version=5"
      }
    ],
    [
      {
        "version": 5,
        "isBranch": true,
        "changeDate": "2014-03-19T17:23:59.697Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample",
        "isFolder": true,
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample?versionType=Changeset&version=5"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.sln?versionType=Changeset&version=9"
      },
      {
        "version": 5,
        "changeDate": "2014-03-19T17:23:59.697Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.vssscc",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/AuthSample.vssscc?versionType=Changeset&version=5"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code",
        "isFolder": true,
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code?versionType=Changeset&version=9"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code/App.config",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code/App.config?versionType=Changeset&version=9"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code/AuthSample.cs",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code/AuthSample.cs?versionType=Changeset&version=9"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code/AuthSample.csproj.vspscc",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code/AuthSample.csproj.vspscc?versionType=Changeset&version=9"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code/AuthSample.csproj",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code/AuthSample.csproj?versionType=Changeset&version=9"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code/Properties",
        "isFolder": true,
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code/Properties?versionType=Changeset&version=9"
      },
      {
        "version": 9,
        "changeDate": "2014-03-21T19:32:02.213Z",
        "path": "$/Fabrikam-Fiber-TFVC/AuthSample/Code/Properties/AssemblyInfo.cs",
        "url": "https://mytfsserver/DefaultCollection/_apis/tfvc/items/%24/Fabrikam-Fiber-TFVC/AuthSample/Code/Properties/AssemblyInfo.cs?versionType=Changeset&version=9"
      }
    ]
  ]
}

Get a specific version

You can indicate which version to get when you get a file, zip a folder, or get item metadata.

Parameter	Type	Default
versionType	enum { Branch, Changeset, Shelveset, Change, Date, MergeSource, Latest}	Branch
version	string	master
versionOptions	enum { None, Previous, UseRename }	None

Use the versionType and version parameters together. For example, to get an item from "mybranch", use versionType=branch&version=mybranch.

If `versionType` is...	`Version` is interpreted as...
Changeset	ID of a changeset.
Shelveset	ID of a shelveset.
Change	ID of a change.
Date	At this time.
MergeSource	ID of the changeset that is the source of the merge.
Latest	n/a

You can also modify the version with the versionOptions parameter.

Value	Effect
UseRename
Previous	The last version of the item that was changed prior to the version specified by the `versionType` and `version` parameters.
None	No modification to the version specified by the `versionType` and `version` parameters.

When you specify a version with recursion, the version is applied to the item and its children.

แชร์ผ่าน

Version control items

Get a file

Using path as query parameter

Request

Response

Status code: 200

Request

Response

Status code: 200

Get item metadata for

A file

Sample request

Response

Status code: 200

A folder

Sample request

Sample response

A folder and its children

Sample request

Sample response

Multiple items

Sample request

Sample response

Get a specific version

แหล่งทรัพยากรเพิ่มเติม