API操作マニュアル

1.はじめに

1.1 本マニュアルの目的

シェアドモビリティ最適配置デモアプリで提供されるAPIの使い方をご紹介します。

1.2 前提条件

FUJITSU Research Portalのアカウントを保有していること。

1.3 API一覧

Social Digital Twin Platformで提供しているAPIの一覧は、以下の手順でFUJITSU Research Portalからご参照ください。

FUJITSU Research PortalにおけるAPI一覧参照手順

FUJITSU Research Portalにログインし、Social Digital Twin Platform のシェアドモビリティ最適配置を選択します。ページ下部のAPIを試すを選択すると、公開されているAPI一覧を参照することができます。

2. APIの実行方法

2.1 FUJITSU Research Portalを利用したAPI実行方法

API一覧画面を開き、実行したいAPIを一覧から選択します。

APIの仕様を確認し、Try itを選択します。

画面右側にAPIの試行画面が表示されます。Social Digital Twin Platformで提供するAPIを利用するためには、アクセストークンが必要になるため、Authorization flow: authorization_code を選択します。選択することで、自動的にアクセストークンが発行されます。

リクエスト内容を確認し、Sendボタンを実行することでAPIが実行されます。

2.2 Bash等を利用したAPI実行手順

アクセストークンの発行

FUJITSU Research PotalのAPI一覧画面から取得できます。 2.1 FUJITSU Research Portalを利用したAPI実行方法と同様に、Social Digital Twin Platformで提供されるAPIの試行画面を開き、Authorization flow: authorization_code を選択します。生成されるアクセストークンをAuthorizationヘッダーからコピーします。

※(ご参考)FUJITSU Research Portal-ドキュメントに記載のAPIアクセストークン発行方法[PDF]に従いアクセストークンを発行することも可能です。

変数のセットアップ FUJITSU Research Portal日本語版では、以下のエンドポイントを利用します。
```
API_GATEWAY="https://apigateway.research.global.fujitsu.com"
TOKEN="Bearer 取得したToken情報"
```
curlを利用したAPIの実行例 API試行画面でcurlを選択することで取得可能です。

APIの実行:シミュレーション一覧取得APIを実施した場合

curl -X GET "${API_GATEWAY}/sdtp/api/simulations" -H "Cache-Control: no-cache" -H "Authorization: ${TOKEN}"

API実行結果例

[{"id":"sim-04d53550-a0b9-4f17-aac1-70aa5ed3fcd5","name":"TEST_Silumation","createdAt":"2023-12-13T09:21:13.646Z","start":5,"end":6,"status":"finished"}]

3.手順-指定したデータや都市でデジタルリハーサルを実行する

準備

対象都市用に以下のファイルと情報を作成する必要があります。

SUMOのネットファイル（map.net.xml.gz）
人の移動を定義するODファイル（od.csv.gz）
escooterの貸出・返却をするステーションのファイル（stations.csv）
シミュレーション条件パラメータファイル（condition.json）

データの作成は、データ作成マニュアルをご参照ください。

本編では、2.2 bash等を利用したapi実行手順での実行例を記載します。

FUJITSU Research Portal日本語版では、以下のエンドポイントを利用します。以下のように変数の設定をしてください。

API_GATEWAY="https://apigateway.research.global.fujitsu.com"
TOKEN="Bearer 取得したToken情報"

上記が用意出来たら、ファイルを登録します。

ファイル登録

map.net.xml.gz、od.csv.gz、stations.csv、condition.jsonファイルをデータ登録APIを使ってアップロードします。

curl -X POST -F "filename=map.net.xml.gz" -F "content=@map.net.xml.gz"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

curl -X POST -F "filename=od.csv.gz" -F "content=@od.csv.gz"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

curl -X POST -F "filename=stations.csv" -F "content=@stations.csv"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

curl -X POST -F "filename=condition.json" -F "content=@condition.json"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

結果例:

{"simdataId":"simdata-6fd5b0e7-dadd-4678-862e-518213383fd2"}

ファイルサイズが大きい場合(リクエストのサイズが3MBを超える場合)、2.1 FUTJITSU Research Portalを利用したapi実行方法で利用可能なリクエストサイズの制限を超えてしまい、エラーとなります。2.2 bash等を利用したapi実行手順をご利用ください。

登録されたsimdataIdを用いてenv.jsonを作成して、アップロードします。

curl -X POST -F "filename=env.json" -F "content=@env.json"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

デジタルリハーサルの実行

登録したenv.jsonのsimdataIdを指定して、デジタルリハーサル開始APIを実行します。

echo '{"simdataId":"simdata-0c1d8713-7477-4466-b82a-b9eafe11226c"}' | \
curl -X POST -H "Authorization: ${TOKEN}" -H Content-Type:application/json -d @- "${API_GATEWAY}/sdtp/api/simulations"

結果例:

{"id":"sim-d2ee69a1-bb6f-4821-9978-ef92176dbed8"}

デジタルリハーサル一覧

デジタルリハーサル一覧取得APIにより、実行状態statusを確認できます。

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations"

結果の整形例:

[
  {
    "id": "sim-ddb56e15-d07e-42d8-bc39-d22f11df4e11",
    "name": "09/06_16:58:04",
    "createdAt": "2023-09-06T07:58:15.070Z",
    "start": 5,
    "end": 12,
    "precipitation": 0,
    "status": "finished"
  },
  {
    "id": "sim-d2ee69a1-bb6f-4821-9978-ef92176dbed8",
    "name": "09/06_17:04:16",
    "createdAt": "2023-09-06T08:04:26.436Z",
    "start": 5,
    "end": 12,
    "precipitation": 0,
    "status": "error"
  }
]

デジタルリハーサル結果取得

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations/sim-ffcafba6-5bc0-432d-ab56-ae2c2757733e"

結果の整形例:

{
  "status": "finished",
  "simulation": {
    "id": "sim-ddb56e15-d07e-42d8-bc39-d22f11df4e11",
    "condition": {
      "name": "09/06_16:58:04",
      "seed": 0,
      "createdAt": "2023-09-06T07:58:15.070Z",
      ...
    },
    "resultFiles": ["output.txt", "states.txt", "current-usage.txt", "total-usage.txt", ...]
  }
}

デジタルリハーサル結果ファイル取得

結果ファイルの内容は、デジタルリハーサルを実行するユースケースに応じて、データ作成マニュアルを参照してください。

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations/sim-b483240d-f761-4248-8fbf-8e3bcf4da7f1/states.txt"

グラフィカルに動きを確認したい場合は、デモアプリでもAPIの実行結果を確認できます。デモアプリにアクセスし、シミュレーション結果を確認してください。

デジタルリハーサル停止・削除

curl -X DELETE -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations/sim-b483240d-f761-4248-8fbf-8e3bcf4da7f1"

デジタルリハーサルデータ一覧

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simdata"

結果の整形例:

[
  {
    "simdataId": "simdata-6fd5b0e7-dadd-4678-862e-518213383fd2",
    "filename": "od.csv.gz",
    "createdAt": "2023-09-13T08:25:05.533Z",
    "metadata": {
      "tag": "od1"
    }
  },
  {
    "simdataId": "simdata-0c1d8713-7477-4466-b82a-b9eafe11226c",
    "filename": "env.json",
    "createdAt": "2023-09-06T08:04:26.574Z",
    "metadata": {
      "simname": "09/06_17:04:16"
    }
  }
]

デジタルリハーサルデータmetadata更新

登録ファイルのmetadataは後から更新が可能です。値にnullを指定すると該当キーを削除します。

echo '{"scenario":"2","tag":null}' | \
curl -X PATCH -H "Authorization: ${TOKEN}" -H "Content-Type:application/json" -d @- "${API_GATEWAY}/sdtp/api/simdata/simdata-00da2bcc-f54f-440f-9095-1a0ec416f0e2/metadata"

結果例:

{"scenario":"2"}

デジタルリハーサルデータ削除

curl -X DELETE -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simdata/simdata-00da2bcc-f54f-440f-9095-1a0ec416f0e2"