REST API
Bitbucket Cloud REST API version 1 has been removed
Read the deprecation notice for more information, or you can go right to the version 2.0 REST API documentation.
オープン標準に基づいた Bitbucket の REST API を使用することで、API にアクセス可能な任意の Web 開発言語を使用してサードパーティ アプリケーションを構築できます。
API を使用することで、ユーザーはアプリケーションにサインインし、ユーザーの代わりに操作を実行することを許可できます。その後、アプリケーションは API を経由して、Bitbucket Cloud のリソース (個人またはチーム アカウント、リポジトリ) や、それらのリソースのさまざまな要素 (チェンジセットやコメントなど) にアクセスできます。
Bitbucket Cloud 用 Atlassian Connect
Bitbucket Cloud との連携を構築できます。
Bitbucket 用 Atlassian Connect を使用することで、Bitbucket Cloud の UI への構築を行うことができます。
連携機能を開発するにあたり、REST アーキテクチャの操作を習得している必要があります。インターネットには、REST に関する多数の優れた資料があります。Bitbucket での REST の実装について理解するには、この概要ページをご参照ください。開始する準備が整ったら、アプリケーションのコンシューマ キーを取得します。
URI 構造とメソッド
All Bitbucket Cloud requests start with the https://api.bitbucket.org/2.0 prefix (for the 2.0 API). The next segment of the URI path depends on the endpoint of the request. For example, using the curl command and the repositories endpoint you can list all the issues on Bitbucket's tutorial repository:
$ curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org
特定のエンドポイントを指定して、そのエンドポイントの詳細な情報やリソースを取得することができます。例として、リポジトリの issues リソースがあります。
$ curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org/issues
エンドポイントやリソースには、一覧のアクション (またはメソッド) が関連付けられています。Bitbucket サービスでは、次の標準 HTTP メソッドがサポートされます。
| 呼び出し | 説明 |
|---|---|
GET |
情報を取得します。 |
PUT |
既存の情報を更新します。 |
POST |
新しい情報を作成します。 |
削除 |
既存の情報を削除します。 |
たとえば、issues リソースで POST アクションを呼び出して、課題トラッカーで課題を作成できます。
コンテンツ長の指定について
411 Length Required r レスポンスが返される場合があります。この場合、API は Content-Length ヘッダーを要求していますが、クライアントがそれを送信していません。したがって、手動でヘッダーを追加する必要があります。たとえば、curl クライアントを使用する場合は次のようになります。
$ curl -r PUT --header "Content-Length: 0" -u user:pass https://api.bitbucket.org/2.0/emails/rap@atlassian.com
Universally Unique Identifier (UUID)
UUID は、ユーザー、チーム、およびリポジトリ向けに単一の識別子を提供します。UUID は、ユーザー名、チーム名、リポジトリ名のフィールドとは独立しており、このようなフィールドが変更されても同じ値が保持されます。たとえば、ユーザーがユーザー名を変更したり、リポジトリを移動した場合、それらへの ID を使用している呼び出しを修正する必要がありますが、UUID を参照している場合は修正は不要になります。
UUID の例と構造
UUID's work with 2.0 APIs for the user, team, and repository
以降の例では、次の文字を中括弧の代わりに使用しています。 %7B は { 、 %7D は } の代用です。
ユーザー
ユーザー名での呼び出し
$ curl https://api.bitbucket.org/2.0/users/tutorials
{
"username": "tutorials",
"website": "https://tutorials.bitbucket.org/",
"display_name": "tutorials account",
"uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/users/tutorials"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/tutorials"
},
"html": {
"href": "https://bitbucket.org/tutorials"
},
"followers": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
},
"avatar": {
"href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
},
"following": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/following"
}
},
"created_on": "2011-12-20T16:34:07.132459+00:00",
"location": "Santa Monica, CA",
"type": "user"
}UUID での呼び出し
$ curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D
{
"username": "tutorials",
"website": "https://tutorials.bitbucket.org/",
"display_name": "tutorials account",
"uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/users/tutorials"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/tutorials"
},
"html": {
"href": "https://bitbucket.org/tutorials"
},
"followers": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
},
"avatar": {
"href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
},
"following": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/following"
}
},
"created_on": "2011-12-20T16:34:07.132459+00:00",
"location": "Santa Monica, CA",
"type": "user"
}
チーム
チーム名での呼び出し
$ curl https://api.bitbucket.org/2.0/teams/1team
UUID での (チーム リポジトリの) 呼び出し
$ curl https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7D
リポジトリ
リポジトリの UUID を取得した場合、API 呼び出しでのユーザー名やチーム名は不要になります。この場合、空白のフィールドを使用できます。これにより、ユーザー名やチーム名に変更があっても対象のリポジトリを解決できます。
チーム名が 1team、リポジトリ名が moxie の場合
$ curl https://api.bitbucket.org/2.0/repositories/1team/moxie
{
"updated_on": "2013-11-08T01:11:03.263237+00:00",
"size": 33348,
"is_private": false,
"uuid": "{21fa9bf8-b5b2-4891-97ed-d590bad0f871}"
}
UUID の場合
With empty field:
$ curl https://api.bitbucket.org/2.0/repositories/%7B%7D/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
With team name
$ curl https://api.bitbucket.org/2.0/repositories/1team/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
サポート対象のエンドポイントおよびそれらのリソース
Bitbucket Cloud は複数のエンドポイントをサポートします。エンドポイントは追加リソースを持つ場合があります。次の表は、エンドポイントと、それらに関連付けられたリソースを示しています。
| エンドポイント | 説明 | |
|---|---|---|
group-privileges |
グループのリポジトリ権限を管理します。 | |
groups |
グループとグループのメンバーシップを管理します。 | |
invitations |
ほかのユーザーをリポジトリに招待します。 | |
privileges |
自身のリポジトリでの個人ユーザーの権限を管理します。 | |
|
リポジトリのリソースを管理します。このエンドポイントは次のリソースをサポートします。 | |
changesets |
リポジトリのチェンジセットを管理します。 | |
deploy-keys |
製品ビルドのデプロイに使用する ssh キーを管理します。 |
|
events |
公開リポジトリのイベントを追跡します。 | |
followers |
リポジトリをフォローしているアカウントを一覧で取得できます。 | |
issues |
課題トラッカーと、それに関連付けられた課題を管理します。 | |
links |
Jira、Bamboo、およびカスタム リンク リソースとの連携を管理します。 | |
pullrequests |
プル リクエストのコメントに関連付けられたコメントやいいねを管理します。 | |
repository |
リポジトリに関連付けられたブランチ、タグ、およびマニフェストを管理します。 | |
services |
1 つのアカウントに連携されたサービスを管理します。 | |
src |
リポジトリ内の特定のファイルやディレクトリの情報を取得します。 | |
wiki |
wiki 内のページの情報を取得します。 | |
user |
現在認証されているアカウントのプロファイルを管理します。 | |
users |
特定の個人アカウントの関連情報を管理します。このエンドポイントは次のリソースをサポートします。 | |
account |
1 つのアカウントの関連情報を取得します。 | |
emails |
1 つのアカウントに関連付けられたメール アドレスを管理します。 | |
invitations |
1 つのアカウントが送信した招待を管理します。 | |
oauth |
1 つのアカウントに関連付けられたコンシューマを管理します。 | |
privileges |
チームの権限設定を管理します。 | |
ssh-keys |
1 つのアカウントの ssh キーを管理します。 | |
teams |
チームの関連情報を取得します。 | |
認証
Bitbucket Cloud API には、公開データへのアクセス権は認証なしで付与されます。非公開データへのアクセスでは、呼び出し元がアクセス権を持つアカウントの情報で認証を完了する必要があります。たとえば、アカウントのメール アドレスなどの管理対象のデータを参照する場合、アカウント所有者か、チームの場合はチームへの管理アクセスを持つチーム メンバーとして認証を行う必要があります。アプリケーションのテストを行っている場合、cURL などのクライアントを BASIC 認証 (ユーザー名 / パスワード、2 段階認証を有効化している場合はユーザー名 / アプリ パスワード) と組み合わせて使用することができます。たとえば次の curl 呼び出しは、buser の公開および非公開リポジトリを一覧表示します。
$ curl --user buserbb:2934dfad https://api.bitbucket.org/2.0/user/repositories
Bitbucket と連携するアプリケーションを構築している場合、コンシューマ キーを取得し、OAuth 2.0 フレームワークを使用して認証します。OAuth と Bitbucket の詳細については、このドキュメントの「Bitbucket Cloud での OAuth」をご参照ください。