SW360でREST APIを使ってみよう

はじめに

前回取り上げたSW360ですが、自動化のためのREST APIが準備されています。SW360のインスタンスにはREST APIのガイドも用意されていますが、本体のバージョンアップに追い付いていないため、そのままでは実行できません。
今回は、実際にSW360のREST APIを利用についてご紹介します。

この記事でお伝えしたいこと

SW360( sw360-15.0.0-M1 )のREST APIを利用するための準備と、コンポーネントやプロジェクトの情報取得や設定を行うまでを解説します。
以下のような方が読まれることを想定しています。

• SW360のREST APIを試してみたい方。

また、以下の知識を必要とします。

• Linuxに関する知識。
• REST APIに関する知識。
• curlに関する知識。

解説の流れ

SW360でREST APIを利用するには次の流れになります。

• クライアントの登録
  • client_id/client-secretの取得
  • クライアントの削除
• 認証トークンの取得
  • Login情報による取得
• REST API呼び出し

環境

検証環境

本記事では以下のような環境を想定して説明を行います。処理の実行については、基本的にSW360サーバー上で実行します。

• SW360サーバー
  • OS
    • Ubuntu 20.04 LTS
  • SW360バージョン
    • sw360-15.0.0-M1
  • SW360アカウント情報
    • UserID: admin@sw360.org
    • Password: 12345
  • クライアントツール
    • curl
    • jq

準備

クライアントの登録

REST API利用するにあたり、アクセス可能なクライアントを登録し、IDとSecretを取得する必要があります。
GUIを利用する方法と、コマンドにて登録する方法があります。Tokenのタイムアウトは3600秒、READ/WRITE権限で登録します。

[コマンド例]
SW360_USER=admin@sw360.org  # SW360のシステム管理権限を持つユーザー
SW360_PW=12345              # ユーザーのログインパスワード
SW360_HOST=http://localhost # SW360サーバー
curl -s -S \
     --user "${SW360_USER}:${SW360_PW}" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -X POST ${SW360_HOST}/authorization/client-management \
     -d '{
    "description" : "REST API client",
    "authorities" : [ "BASIC" ],
    "scope" : [ "READ", "WRITE" ],
    "access_token_validity" : 3600,
    "refresh_token_validity" : 3600
}'

{
    "description" : "REST API client",
    "client_id" : "93079a408d6dff0691be044f4c0018ad",
    "client_secret" : "53568c3c-35b8-4451-adb8-c075e4f03a21",
    "authorities" : [ "BASIC" ],
    "scope" : [ "READ", "WRITE" ],
    "access_token_validity" : 3600,
    "refresh_token_validity" : 3600
}

この作業は1度実施すれば、次回以降同じ情報を利用できます。登録した情報は、 OAuth Client ページまたは http://localhost/authorization/client-management にて参照可能です。

クライアントの削除

不要になったクライアントは OAuth Client ページにて削除できます。以下のように、curlコマンドを用いてWebAPIを経由して削除することもできます。

[コマンド例]
SW360_USER=admin@sw360.org  # SW360のシステム管理権限を持つユーザー
SW360_PW=12345              # ユーザーのログインパスワード
SW360_HOST=http://localhost # SW360サーバー
CLIENT_ID=93079a408d6dff0691be044f4c0018ad # クライアントの登録で取得した client_id
curl -s -S \
    --user "${SW360_USER}:${SW360_PW}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    -X DELETE ${SW360_HOST}/authorization/client-management/${CLIENT_ID}

認証トークンの取得

API実行に利用するBearerTokenを取得します。

Login情報による取得

ユーザーのログインIDとパスワードで認証を行います。

[コマンド例]
SW360_USER=admin@sw360.org  # SW360のシステム管理権限を持つユーザー
SW360_PW=12345              # ユーザーのログインパスワード
SW360_HOST=http://localhost # SW360サーバー
CLIENT_ID=93079a408d6dff0691be044f4c0018ad         # クライアントの登録で取得した client_id
CLIENT_SECRET=53568c3c-35b8-4451-adb8-c075e4f03a21 # クライアントの登録で取得した client_secret
curl -s -S \
    --user "${CLIENT_ID}:${CLIENT_SECRET}" \
    -d "grant_type=password&username=${SW360_USER}&password=${SW360_PW}" \
   -X POST ${SW360_HOST}/authorization/oauth/token -k

認証が成功すると、以下のような結果が取得できます。

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3czNjAtUkVTVC1BUEkiXSwidXNlcl9uYW1lIjoiYWRtaW5Ac3czNjAub3JnIiwic2NvcGUiOlsiUkVBRCIsIldSSVRFIl0sImV4cCI6MTY1NTM2NDIwNSwiYXV0aG9yaXRpZXMiOlsiUkVBRCIsIldSSVRFIl0sImp0aSI6Ijk4YTc3NGRjLTVhYTUtNDUyZC04N2ZkLTBkY2U1YWJkZDljYSIsImNsaWVudF9pZCI6IjkzMDc5YTQwOGQ2ZGZmMDY5MWJlMDQ0ZjRjMDAxOGFkIn0.Aqfu72tPoINmD1d8_CUcDGX_jC5IkKDaz1Kxw_m18i2Nrt6X9U-OiQthDC0MXRRxrnHveb-lME9yE8uVQT6bdinalQKKpmc5qUT_sxyKG-gXviCm0lNbxhSX1OmiffV4e-Fy_QOEfRDZrWYxLHNwwNRReqvDwor339Q56eexXr3-3CNrEjCvjZnL5Ig7_wMpIrfi0eEEmdm7DAVxQ1WDvlCu6wnD75PkfJ-Zol-4PkhTc7sqyEScJELiAREv0475ze3wdLQ_6zSZOGsyKfENMZDB6k85QdRxDpRMM3Q9365laMcJAVFwZ7d1jv0IAe2AsM4SqYKBPyFcgk0yZVpfOA",
  "token_type" : "bearer",
  "refresh_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3czNjAtUkVTVC1BUEkiXSwidXNlcl9uYW1lIjoiYWRtaW5Ac3czNjAub3JnIiwic2NvcGUiOlsiUkVBRCIsIldSSVRFIl0sImF0aSI6Ijk4YTc3NGRjLTVhYTUtNDUyZC04N2ZkLTBkY2U1YWJkZDljYSIsImV4cCI6MTY1NTM2NDIwNSwiYXV0aG9yaXRpZXMiOlsiUkVBRCIsIldSSVRFIl0sImp0aSI6IjQ0OWQzNWY5LTFiMzMtNDVhZC1iMDM4LTA0ZDM1MWUyNWU4OSIsImNsaWVudF9pZCI6IjkzMDc5YTQwOGQ2ZGZmMDY5MWJlMDQ0ZjRjMDAxOGFkIn0.WoGWuKB2qTZ02kwNaZO_wUv7mfGd-yrHhvRmD3YsP2AuZ-vzIPm1vGDNH4VifN3crjd0GwBGTlQj4FLMiN02-fcOl7FM06vINmdJy5y3UTuESiqa9-Ks3GhfJPN7UEDJ_mNNJ4-U9nAmF1XM_f4oDfALOe_WtsVKuUEcQxOhmrsFeuQiXWbgJNgfYd3Jv3ofuxqMBaQwxhpkKbFWeyhfU7eRJHawnmiPUxa2Ej3v2nwtZL868I7jzSJj5LdTsGMV3XUwamB8qYynLSda3R3a63xDVLvSWYHqKgdLFN4kK7UqRi_PMg5RgbQHIghyPEORNzuW15pVGcYPdKiC-oXIqw",
  "expires_in" : 3599,
  "scope" : "READ WRITE",
  "jti" : "98a774dc-5aa5-452d-87fd-0dce5abdd9ca"
}

Bashなどで利用する場合、以下のように変数へ格納するのも良いでしょう。

[コマンド例]
BEARER_TOKEN=$(curl -s -S \
    --user "${CLIENT_ID}:${CLIENT_SECRET}" \
    -d "grant_type=password&username=${SW360_USER}&password=${SW360_PW}" \
   -X POST ${SW360_HOST}/authorization/oauth/token | jq -r .access_token)

REST APIの実行

基本のAPI呼び出し

API情報はインスタンスの /resource/docs/api-guide.html にあります。
ただし、sw360-15.0.0-M1に関しては、ガイドに記載されているREST APIのURL ホスト名/api/～ を ホスト名/resource/api/～ と読み替えてください。
基本の呼び出し例として、プロジェクトの一覧を取得します。

[コマンド例]
SW360_HOST=http://localhost # SW360サーバー
BEARER_TOKEN=eyJhbGciOiJSUzI1Ni(省略) # 認証で取得した access_token
curl -s -S -X GET \
    -H "Authorization: Bearer ${BEARER_TOKEN}" \
    -H "Accept: application/hal+json" \
    "${SW360_HOST}/resource/api/projects"

以降の説明では、 SW360_HOST および BEARER_TOKEN の設定に関しては記述を省略します。内容は上記を参照してください。

参照系APIの例

参照のAPI例です。複数の結果が返る参照系APIには、ソートやページネーション、フィルタなどのオプションがあります。

• コンポーネント一覧:名前降順ソート、ページネーションあり(項目数100、先頭ページ指定)

[コマンド例]
curl -s -S -X GET \
    -H "Authorization: Bearer ${BEARER_TOKEN}" \
    -H "Accept: application/hal+json" \
    "${SW360_HOST}/resource/api/components?page=0&page_entries=100&sort=name%2Cdesc"

• コンポーネント一覧:名前("Commons IO")フィルタあり

[コマンド例]
curl -s -S -X GET \
    -H "Authorization: Bearer ${BEARER_TOKEN}" \
    -H "Accept: application/hal+json" \
    "${SW360_HOST}/resource/api/components?name=Commons%20IO"

設定系APIの例

設定のAPI例です。追加はPOST、更新はPATCHメソッドで実行します。ボディにJSON形式で登録情報を指定してください(必須項外の項目は省略も可能です)。また、ヘッダーに"Content-Type: application/json"を設定することを忘れないようにしてください。

• コンポーネント追加

[コマンド例]
curl -s -S -X POST \
    -H "Authorization: Bearer ${BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/hal+json" \
    "${SW360_HOST}/resource/api/components" \
    -d '{
        "componentType" : "OSS",
        "name" : "ApiSample",
        "description" : "ApiSample is REST API Sample"
    }'

bashの変数に格納した情報を利用して更新することもできます。また、日本語の文字列も可能です。その場合は文字コードに注意してください。

• コンポーネント更新

[コマンド例]
EXTERNAL_ID=3fc7d483-6bfc-4acc-a8ff-4882d2dc9ac4 # external_id
COMPONENT_ID=b1a66ee4f13e47938825f01c686b315e # component_id
curl -s -S -X PATCH \
    -H "Authorization: Bearer ${BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/hal+json" \
    "${SW360_HOST}/resource/api/components/${COMPONENT_ID}" \
    -d @- <<EOF
{
        "externalIds" : {
            "bd-component-id" : "${EXTERNAL_ID}"
        },
        "componentType" : "OSS",
        "description" : "サンプルコンポーネントです"
}
EOF

コンポーネントを指定するcomponent_idは、コンポーネント追加の戻り値や、コンポーネント一覧の結果などから取得してください。

REST APIの注意

APIガイドの情報に関し、必要なリクエストパラメータなどが不明なケースなどがあります。実行結果のレスポンスを参考にすることもできますが、以下のリリース更新のライセンス指定などは、まったく異なるので注意が必要です。

• リリース更新

[コマンド例]
RELEASE_ID=99fa97a98a6f44b9a755a026cdf47847 # release_id
curl -s -S -X PATCH \
    -H "Authorization: Bearer ${BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/hal+json" \
    "${SW360_HOST}/resource/api/releases/${RELEASE_ID}" \
    -d '{
        "mainLicenseIds": ["Apache-2.0"]
    }'

メインのライセンスは、プロパティ mainLicenseIds に対し、登録済みのライセンスIDの配列を指定する必要があります。

さいごに

基本的なREST APIの呼び出しについて説明してきましたが、今後も情報をお伝えしていきたいと考えています。
もう少し詳しい情報が欲しいなどのご相談がありましたら、こちらからお気軽にお問い合わせください。