要約

このナレッジベースの記事では、Bitbucket Cloud API を使用してレポートを生成する方法について説明します。

環境

Bitbucket Cloud

ソリューション

Please use the following guidelines to generate the reports.

• There are various APIs available like Workspaces, Projects, Repositories, etc. Please familiarize yourself with them and understand their capabilities and available data structure to verify if they can be helpful for your requirements. Each API serves a unique requirement.

• Familiarize yourself with the following APIs, methods, and capabilities to obtain optimized and successful results

  • Authentication method (認証方法) - さまざまな認証方法を利用できます。自身の組織に合ったものを使用してください

  • Pagination (改ページ) - API から返される出力結果が大きく、1 回の API 呼び出しですべてのデータを返すことができない場合、pagination が役立ちます。

  • Filtering (フィルタリング) - 特定の値についてのみ出力を取得する必要がある場合があります。このような場合には、フィルタリングが役に立ちます。

  • Partial response (部分応答) - API から返されるすべてのデータを取得するのではなく、特定のフィールドのデータのみを取得したい場合に使用します。

  • UUID (汎用一意識別子) - Bitbucket は UUID を使用してさまざまなオブジェクトを一意に識別します。引数として UUID を要求できる API があります。

• 要件によっては、複数の API を使用してレポートを生成する必要がある場合があります。使用する API の数は、要件に完全に依存します。

例

要件

特定のプロジェクトに属するワークスペースからリポジトリのリストを CSV で生成する

• ワークスペース名: workspace_rocket
  

• プロジェクト名: project_atlas 

• 生成するレポートのフィールド: Repository name 

• 生成するレポートの CSV ファイル名: repository_list.csv 

実装アプローチ

• ここでの要件は、ワークスペース内のリポジトリのリストを取得することです。そのため、Workspace API の List repositories を使用します。

• Basic 認証方法 (Bitbucket ユーザー名とアプリ パスワード) を使用できます。

• フィルタリングを使用して、workspace_rocket にあるリポジトリのうち、project_atlasプロジェクトに属するものだけを取得するようにフィルタリングします。query=project.key="project_atlas" 

• リポジトリ名のみを取得するには、部分応答を使用します。fields=values.full_name 

• API とやり取りして CSV ファイルを生成するためのプログラミング言語として Python を使用しますが、API 呼び出しや CSV ファイルの作成など、その他の必要なプロセスを実行できれば任意の言語を使用できます。

$ Curl -X GET -u <username>:<apppassword> "https://api.bitbucket.org/2.0/repositories/{workspace}?q=project.key=%22{KEY}%22&fields=values.full_name"

{
  "values": [
    {
      "full_name": "{workspace}/{repository_1}"
    },
    {
      "full_name": "{workspace}/{repository_2}"
    },
    {
      "full_name": "{workspace}/{repository_3}"
    }
  ]
}

from requests import Session
from csv import writer

username  = "" # Your Bitbucket Cloud username
password  = "" # Your App Password
workspace = "workspace_rocket" #  Your Workspace ID
project   = "project_atlas" # The Project Key

URL = f"https://api.bitbucket.org/2.0/repositories/{workspace}?q=project.key=%22{project}%22&fields=values.full_name"

session = Session()
session.auth = (username,password)

def get_repos(page=None, limit=1_000):
    while True:
        params = {'page': page, 'limit': limit}
        r = session.get(URL, params=params)
        r_json = r.json()
        for raw_repo in r_json.get('values'):
            yield raw_repo.get('full_name')

        if page == None:
            page = 1

        if r_json.get('next'):
            page += 1
        else:
            return

def main():
    # Export the data to a CSV file
    with open(f'repository_list.csv', 'x', newline='') as file:
        writer_object = writer(file)
        writer_object.writerow(['Repository Name',])
        
        for repo in get_repos():
                writer_object.writerow([repo])
    
    print("Done")


if __name__ == '__main__':
    main()

実践のヒント

• 同じ API 呼び出しでフィルタリングや部分応答などの複数の機能を使用している場合は、& 演算子を使用してください。

• 慣習として、まずターミナルまたは Postman などのその他のツールで curl を使用して API 呼び出しを実行し、正しいエンドポイントにアクセスして必要なデータを取得していることを確認してください。出力結果が問題なく、返されるフィールドを把握できたら、スクリプトで使用できます。

• API レスポンスから特定のフィールドのみを取得したいと考えるかもしれません。すべての結果は values という名前のリストで返されることに注意してください。そのため、これらの特定のフィールドを取得するには、URL エンドポイントの一部としてそれらを提供する必要があります。

  https://api.bitbucket.org/2.0/repositories/{workspace}?fields=values.full_name 

• API 呼び出しを実行している場所によっては、二重引用符 (") など、一部の文字を URL エンコードする必要がある場合があります。上の例では、URL 内の二重引用符は %22 にエンコードされています。