FOSSologyでREST APIを使ってみよう

検証環境

本記事では以下の環境にて操作を行っています。

• サーバー
  • FOSSology v3.11.0 (Docker image)
  • Docker version 20.10.7
• クライアント
  • WSL2(Kernel v5.10.60.1 / Ubuntu-20.04)
  • 以下のコマンドを使用します。事前にインストールしておいてください。
    • jq
    • curl

事前準備

REST APIを利用するには認証のためのトークンが必要になります。事前にFOSSologyにブラウザーでアクセスして、トークンを生成する必要があります。

1. FOSSologyにログインし、メニューの [Admin] > [Users] > [Edit User Account] を選択します。
2. [Create a new token]で必要事項（Name / Expire at）を設定します。Access scope は Read/Write accessを選択してください。
3. "Create new token"ボタンを押してトークンを生成します。
4. 認証に必要なトークンが表示されるので、メモしてください。

画面をリロードすると、トークンが非表示になります。その場合は、Active access tokensリストに表示される対象トークンの"Reveal"ボタンにて再表示してください。

REST API呼び出しの基本

FOSSologyでは、Bearer認証が利用されています。具体的には、取得したトークンをHTTPのAuthorizationヘッダに指定して対象のURLにアクセスします。

例えば、curlでAPIを呼び出すにはリクエストヘッダ（-H オプション）に "Authorization: Bearer トークン" を指定してコマンドを実行します。
※以降の例では、見栄えのために改行を入れていますが1行で入力してください。

• 例：フォルダ一覧取得

$ curl -sS -X GET http://10.0.11.1/repo/api/v1/folders 
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJl
      eHAiOjE2NjgyOTc1OTksIm5iZiI6MTYzNjY3NTIwMCwianRpIjoiTWk0eiIsInN
      jb3BlIjoid3JpdGUifQ.vr1duV6c13TFlQ2Nh20VUgw0EHeSpjhrZXLhJpvVs5c" | jq

• 結果

[
  {
    "id": 1,
    "name": "Software Repository",
    "description": "Top Folder",
    "parent": null
  }
]

例ではFOSSologyサーバー（http://10.0.11.1）にアクセスし、取得したjsonをjqコマンドで整形しています。サーバー上にはトップフォルダのみ存在していることがわかります。

REST APIの利用方法ですが、以下のように実際に解析に適用しやすいケースを想定して説明します。

1. 格納先フォルダ作成
2. ファイルアップロード
3. ファイルアップロードの結果確認
4. 解析実行
5. 解析実行の結果確認

1. 格納先フォルダ作成

フォルダを作成するには、リクエストヘッダの parentFolder に親フォルダのId、 folderName にフォルダ名を指定して実行します。次の例では、親にトップフォルダ、フォルダ名に rest を指定しています。

$ curl -sS -X POST http://10.0.11.1/repo/api/v1/folders 
  -H "parentFolder: 1" 
  -H "folderName: rest" 
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJl
      eHAiOjE2NjgyOTc1OTksIm5iZiI6MTYzNjY3NTIwMCwianRpIjoiTWk0eiIsInN
      jb3BlIjoid3JpdGUifQ.vr1duV6c13TFlQ2Nh20VUgw0EHeSpjhrZXLhJpvVs5c" | jq

• 結果

{
  "code": 201,
  "message": 3,
  "type": "INFO"
}

実行が成功した場合には、codeに200番台の値が格納されます。 また、messageに新規作成したフォルダのIdが格納されます。次のアップロードにはフォルダのIdが必要になります。

2. ファイルアップロード

ファイルをアップロードするには、リクエストヘッダの folderId にファイルを格納するフォルダのId、uploadDescription にファイルの説明、public にファイルの公開設定、リクエストボディにアップロードするファイル（例ではsample.tar.gz）を指定して実行しています。この例ではマルチパートでファイル送信するため、Content-Typeにmultipart/form-dataを設定しています。

$ curl -sS -X POST http://10.0.11.1/repo/api/v1/uploads 
  -H "folderId: 3" 
  -H "uploadDescription: created by REST" 
  -H "public: public"
  -H "Content-Type: multipart/form-data" 
  -F 'fileInput=@"sample.tar.gz";type=application/octet-stream' 
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJl
      eHAiOjE2NjgyOTc1OTksIm5iZiI6MTYzNjY3NTIwMCwianRpIjoiTWk0eiIsInN
      jb3BlIjoid3JpdGUifQ.vr1duV6c13TFlQ2Nh20VUgw0EHeSpjhrZXLhJpvVs5c" | jq

• 結果

{
  "code": 201,
  "message": 2,
  "type": "INFO"
}

実行が成功した場合には、codeに200番台の値が格納されます。 また、messageにアップロードしたファイルのIdが格納されます。

3. ファイルアップロードの結果確認

ファイルをアップロードの結果を確認するには、対象ファイルのIdをクエリパラメータuploadに指定してステータスを取得します。

$ curl -sS -X GET http://10.0.11.1/repo/api/v1/jobs?upload=2
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJl
      eHAiOjE2NjgyOTc1OTksIm5iZiI6MTYzNjY3NTIwMCwianRpIjoiTWk0eiIsInN
      jb3BlIjoid3JpdGUifQ.vr1duV6c13TFlQ2Nh20VUgw0EHeSpjhrZXLhJpvVs5c" | jq

• 結果

[
  {
    "id": 2,
    "name": "sample.tar.gz",
    "queueDate": "2021-11-12 10:04:44.435339+00",
    "uploadId": "2",
    "userId": "3",
    "groupId": "3",
    "eta": 0,
    "status": "Processing"
  }
]

ファイルのアップロード処理中は、statusが"Processing"となります。しばらく待って再度ステータスを取得しましょう。処理が完了すると、statusが"Completed"となります。次の解析実行は、処理が完了してから実行してください。

4. 解析実行

解析は、リクエストヘッダの uploadId に対象ファイルのId、 folderId にファイルが格納されているフォルダのId、リクエストボディに解析のオプションのjsonデータを指定して実行します。Content-Typeはapplication/jsonとしてください。

$ curl -sS -X POST http://10.0.11.1/repo/api/v1/jobs 
  -H "folderId: 3" 
  -H "uploadId: 2" 
  -H 'Content-Type: application/json' 
  --data '{
    "analysis": {
      "bucket": false,
      "copyright_email_author": false,
      "ecc": false,
      "keyword": false,
      "mime": false,
      "monk": true,
      "nomos": true,
      "ojo": true,
      "package": true
    },
    "decider": {
      "nomos_monk": true,
      "bulk_reused": true,
      "new_scanner": true,
      "ojo_decider": true
    }
  }' 
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJl
      eHAiOjE2NjgyOTc1OTksIm5iZiI6MTYzNjY3NTIwMCwianRpIjoiTWk0eiIsInN
      jb3BlIjoid3JpdGUifQ.vr1duV6c13TFlQ2Nh20VUgw0EHeSpjhrZXLhJpvVs5c" | jq

• 結果

{
  "code": 201,
  "message": 3,
  "type": "INFO"
}

実行が成功した場合には、codeに200番台の値が格納されます。 また、messageに解析のジョブのIdが格納されます。

5. 解析実行の結果確認

解析が正常に終了したか確認するには、対象ジョブのIdをパスパラメータに指定してステータスを取得します。

$ curl -sS -X GET http://10.0.11.1/repo/api/v1/jobs/3
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJl
      eHAiOjE2NjgyOTc1OTksIm5iZiI6MTYzNjY3NTIwMCwianRpIjoiTWk0eiIsInN
      jb3BlIjoid3JpdGUifQ.vr1duV6c13TFlQ2Nh20VUgw0EHeSpjhrZXLhJpvVs5c" | jq

• 結果

{
  "id": 3,
  "name": "sample.tar.gz",
  "queueDate": "2021-11-12 10:44:52.069541+00",
  "uploadId": "2",
  "userId": "3",
  "groupId": "3",
  "eta": 0,
  "status": "Processing"
}

解析処理中は、statusが"Processing"となります。しばらく待って再度ステータスを取得しましょう。処理が完了すると、statusが"Completed"となります。