ある要件でプロジェクトの一覧をAPIで取得する必要がありました。
実行してみたところ20件しか値がとれていないことに気づきました。調べたところデフォルトでは20件しか結果が返されず、全件取得するにはページネーションを使用する必要があることがわかりました。
ここでは全件取得するまでの過程を記載します。
GitLab APIの使用例
ここではprojects APIを例に説明します。
プロジェクトの一覧を取得するためにはProjects APIを使用します。
フォーマットは以下になります。
curl --header "PRIVATE-TOKEN: ${TOKEN}" "${HOST}/api/v4/projects
ただしデフォルトでは結果は20件しか表示されません。
以下のURLのOffset-based paginationにpage と per_page のデフォルト値について記載されています。
結果が何ページに渡るのかを確認するには
結果が20件以上ある場合は、レスポンスが全部で何ページあるのかを取得し、そのページ毎に値を取得するという処理が必要になります。
結果が何ページあるのかを確認するには、レスポンスヘッダーに含まれる x-total-pages の値を確認します。
レスポンスヘッダーを取得するには以下のように --head を指定します。
curl --head --header "PRIVATE-TOKEN: ${TOKEN}" "${HOST}/api/v4/projects
全ページの結果を取得するには
特定のページの値を取得するには
curl --header "PRIVATE-TOKEN: ${TOKEN}" "${HOST}/api/v4/projects?page=2"
というようにページ番号を指定します。（上記は2ページ目を取得している例）
上記のようにページ番号を直接指定していくことで取得は可能ですが、手作業で一つ一つ指定するのは大変です。
そこで以下のような処理を実装することで一度に全件の結果を取得することができます。
- x-total-pagesの値を取得する
- ページの数分ループを回し、各ページの値を取得する
- 結果をCSV等に追記していく
以下にサンプルコードを記載します。
#プロジェクトの一覧を取得するために、レスポンスヘッダーを取得
COMMAND=`curl --head --header "PRIVATE-TOKEN: ${TOKEN}" "${HOST}/api/v4/projects?per_page=$PER_PAGE"`
#レスポンスヘッダーからx-total-pagesの値を取得し、改行を削除、ページ数を取得
PAGES=`echo "$COMMAND" | grep "x-total-pages" | sed 's/x-total-pages: //' | tr -d '\r'`
COUNT=1
#ページの数分ループを実施、ループ内ではページを指定してプロジェクト一覧取得のAPIを実行
while [ $COUNT -le $PAGES ]; do
echo "count = $COUNT"
curl --header "PRIVATE-TOKEN: ${TOKEN}" "${HOST}/api/v4/projects?per_page=$PER_PAGE&page=$COUNT" | jq -r ".[] | [.id ,.name] |@csv" >> result.csv
((COUNT++))
done
参考URL
Projects API
https://docs.gitlab.com/ee/api/projects.html
Bash script to deal with the Gitlab API pagination
https://gist.github.com/gohoyer/73f9ed7919954df55990b61afd716b2e