REST API
Bitbucket Cloud REST API バージョン 1 は削除されました
廃止のご案内を確認するか、バージョン 2.0 の REST API ドキュメントをご参照ください。
限られた 1.0 API リソースの一時的なサポートについて
2.0 REST API では、ユーザーおよびグループ管理は Atlassian Cloud Admin API を使用して行う予定ですが、これらの API エンドポイントはまだ提供されていません。Bitbucket でアトラシアンのプラットフォーム サービスが完全に利用できるようになるまでは、次の 1.0 REST エンドポイントが引き続きサポートされます。
オープン標準に基づいた 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 構造とメソッド
すべての Bitbucket Cloud リクエストは、https://api.bitbucket.org/2.0 プリフィックス (2.0 API の場合) で開始されます。URI パスで続くセグメントは、リクエストのエンドポイントに応じて異なります。たとえば、curl コマンドと repositories エンドポイントを使用することで、Bitbucket のチュートリアル リポジトリのすべての課題を一覧表示できます。
$ 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 | 新しい情報を作成します。 |
DELETE | 既存の情報を削除します。 |
たとえば、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.comUniversally Unique Identifier (UUID)
UUID は、ユーザー、チーム、およびリポジトリ向けに単一の識別子を提供します。UUID は、ユーザー名、チーム名、リポジトリ名のフィールドとは独立しており、このようなフィールドが変更されても同じ値が保持されます。たとえば、ユーザーがユーザー名を変更したり、リポジトリを移動した場合、それらへの ID を使用している呼び出しを修正する必要がありますが、UUID を参照している場合は修正は不要になります。
UUID の例と構造
UUID は 2.0 API で、ユーザー、チーム、およびリポジトリに対して使用できます。
以降の例では、次の文字を中括弧の代わりに使用しています。 %7B は { 、 %7D は } の代用です。
ユーザー
UUID での呼び出し
$ curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7Dチーム
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 | ほかのユーザーをリポジトリに招待します。 | |
users/{accountname}/invitations | 特定のアカウントの招待の一覧を取得します。 | |
認証
Bitbucket Cloud API には、公開データへのアクセス権は認証なしで付与されます。非公開データへのアクセスでは、呼び出し元がアクセス権を持つアカウントの情報で認証を完了する必要があります。たとえば、アカウントのメール アドレスなどの管理対象のデータを参照する場合、アカウント オーナーか、チームの場合はチームへの管理アクセスを持つチーム メンバーとして認証を行う必要があります。アプリケーションのテストを行っている場合、cURL などのクライアントを BASIC 認証 (ユーザー名 / パスワード、2 段階認証を有効化している場合はユーザー名 / アプリ パスワード) と組み合わせて使用することができます。
たとえば次の curl 呼び出しは、bbdocs ユーザーの非公開および公開リポジトリの一覧を取得します。
$ curl --user bbdocs:bbpassword https://api.bitbucket.org/2.0/repositories/bbdocsBitbucket と連携するアプリケーションを構築している場合、コンシューマ キーを取得し、OAuth 2.0 フレームワークを使用して認証します。OAuth と Bitbucket の詳細については、このドキュメントの「Bitbucket Cloud での OAuth」をご参照ください。