概要

WebAPI Overview

ひび割れ自動検出API提供サービスは,お客様独自の点検システムにひび割れ自動検出機能を組み込むことを可能にするサービスです.

一般的なREST APIとなっています.技術的な資料としては,下記の呼出しフローと解説をご覧ください.

ご利用に際しましては,利用登録のほか,当サイトより発行するAPIキーが必要になりますので,個別にお問い合わせください.

WebAPI呼出しフロー

WebAPI Calling Procedure

サインインエンドポイントsigninへ、登録済みのユーザー名とpasswordを送信(POST)要APIキー(x-api-keyヘッダ) Accessトークンが発行されるので取得JSON形式 userurl: 以降利用する専用URL response: トークン情報 URI情報等が発行されるので取得JSON形式 puturis: 画像アップロード先URI geturis: 出力ダウンロード元URI 画像アップロード画像をアップロード先URIへPUT 結果ダウンロード出力をダウンロード元URIからGET 検出方法およびオプションを通知エンドポイントdetectionへ検出モードおよびオプション情報を付加してリクエスト(GET)要Accessトークン(Authrizationヘッダ)要APIキー(x-api-keyヘッダ) No次処理?Yes サインアウトエンドポイントsignoutへリクエスト(GET)要Accessトークン(Authrizationヘッダ)要APIキー(x-api-keyヘッダ) 利用履歴を取得 開始ひび割れ検出終了

WebAPI解説

WebAPI Definition

2021-05-23改定

  1. サインイン時の応答メッセージJSON中に、"profile"を追加しました。
  2. 上記"profile"の値が"complete"または"test"の場合にのみ、有効なアクセストークン(AccessToken)が払い出されます。
  3. サインアウト時の応答メッセージJSON中のsummary(利用履歴サマリー)を変更しました。詳細は、サインアウト SignOut の解説をご参照ください。

2021-04-06改定

  1. サインイン時に発行するトークンをAccessトークンのみにしました
  2. Accessトークンの有効期間を1時間から4時間に延長しました
  3. unifyオプションとsimplifyオプションを削除しました
  4. サインアウト時の利用履歴サマリーを、入力データ数と出力データ数としました
  5. 外部アプリケーションからAPIを呼び出す際にAPIキーが必須になりました

ひび割れ自動検出サービスAPIについて

弊社ひび割れ自動検出サービスAPIのご利用に際しては、サービス利用サイト(https://www.mihari.net)において、あらかじめ所定の登録手続きを完了してください。 本APIを利用するアプリケーションソフトウェア、Webサイトを開発する際にはAPIキーが必要です。APIキーは、同一ソフトウェア、同一のドメインに対し1つ発行されます。 アプリケーションソフトウェア、あるいはWebサイトから本APIを利用する際には、利用者毎に本APIの利用登録をしていただき、サインイン可能なユーザー名とパスワードをご準備いただく必要があります。 本APIのご利用手順の概要を図1に示します。大きく分けて3つの工程があります。サインイン工程、検出工程、サインアウト工程です。それぞれに対し、REST APIでいうところのリソースが割り当てられています。 ご利用開始時にサインインしてAccessトークンを取得し、以降のAPIリクエストではメッセージヘッダにAutorizationを追加し、その値としてAccessトークンをセットする必要があります。



全API共通

本APIを、独自開発のアプリケーションやWebサイトでご利用される際には、アプリケーションソフトウェア毎、あるいはドメイン毎にAPIキーが必要になります。APIキーの発行方法は、https://www.mihari.net にてお知らせしております。発行されたAPIキーは、本APIのメソッドをリクエストする際にx-api-keyヘッダに設定することで、正当なメソッドリクエストとして処理されるようになります。

サインイン SignIn

概要

本APIの利用を開始する際には、ユーザー名とパスワードによってサインインし、Accessトークンを取得しておく必要があります。APIによって検出機能を呼出す場合は、リクエストヘッダにAutorizationヘッダを追加し、取得したAccessトークンをセットする必要があります。Accessトークンの有効期限は取得後4時間です。期限を過ぎた場合は、再度サインインを行い、新しいAccessトークンを取得し直してください。

解説

  1. エンドポイント

    https://api.mihari.net/v1/users/signin

  2. メソッド

    POST

  3. メッセージボディ

    ユーザー名とパスワードを以下のJSON形式でセットします。

         {"username": "ユーザー名",
                "password”: "パスワード"}
  4. オプション

    オプションはありません。

  5. 応答メッセージ

    • 成功時

      • HTTPレスポンスステータスコードは、200です。
      • メッセージ本体は、下記のようなJSONデータです。
          {
                    "message": "signed-in",
                    "userurl": "https://api.mihari.net/v1/users/ユーザー名/",
                    "response": {
                        "AccessToken": "アクセストークン文字列",
                        "ExpiresIn": 14400,
                        "TokenType": "Bearer"
                    },
                    "profile": "登録状況",
                    "timestamp": "日時"
                }
      • "AccessToken": Authorization用のトークン
      • "profile": 登録状況で、値が"complete"なら支払い方法登録も完了しています
      • "timestamp": 受け付けた日時(ISO8601形式)
    • 失敗時

      • HTTPレスポンスステータスコードは、400です。
      • メッセージ本体は、下記のようなJSONデータです。
          {
                    "message": "Error: エラーメッセージ",
                    "timestamp": "日時"
                }



サインアウト SignOut

概要

API利用を終了するには、サインアウトを実行します。IDトークンが有効期限切れになっている場合は既にサインアウト状態になっていますので、サインアウトを呼び出す必要はありません。

解説

  1. エンドポイント

    https://api.mihari.net/v1/users/ユーザー名/signout

  2. メソッド

    GET

  3. ヘッダ

    リクエストヘッダに Authorization を追加し、サインインで取得したIDトークンをセットします。

  4. オプション

    オプションはありません。

  5. 応答メッセージ

    • 成功時
      • HTTPレスポンスステータスコードは、200です。
      • メッセージ本体は、下記のようなJSONデータです。summaryには、当日(today)と前日までの月次集計(monthly) の値が入ります。ただし、当日のデータは、処理と集計のタイミングのずれによって誤差が生じる可能性があります。利用料算出等精度が要求される処理には月次集計(monthly)をお使いください。
          {
                    "message": "signed-out",
                    "username": "ユーザー名",
                    "summary": {
                        "today": {
                            "calls": "検出リクエスト回数",
                            "uploaded": "入力画像を実際にPUTした回数",
                            "size": "PUTした入力画像のファイルサイズの合計",
                            "units": "清算ユニット数"
                        },
                        "monthly": {
                            "calls": "検出リクエスト回数",
                            "uploaded": "入力画像を実際にPUTした回数",
                            "size": "PUTした入力画像のファイルサイズの合計",
                            "units": "清算ユニット数"                        
                        },
                    "timestamp": "日時"}
    • 失敗時
      • HTTPレスポンスステータスコードは、400または403です。
      • メッセージ本体は、下記のようなJSONデータです。
          {"message": "Error: エラーメッセージ",
                 "username": "",
                 "summary": {},
                 "timestamp": "日時"}



ひび割れ検出 Crack Detection

概要

現在はbatchmodeのみ稼働しています。検出対象画像のアップロード先と検出結果のダウンロード元の情報を一括取得(JSON形式。以降、チケットと呼びます)し、やりとりするモードです。

  1. GETメソッドによって、チケットを取得。

  2. 検出対象画像(JPEG形式)を、チケット内の項目「puturis」にあるURIに、PUTメソッドでアップロード。

  3. アップロードしてから待ち時間(約30秒)経過後、チケット内の項目「geturis」にあるURIから、GETメソッドで検出結果(JPEG, DXF, SVG)をダウンロード。

    • 待ち時間は、画像サイズやサービス稼働状況によって変わりますので、あくまでも目安です。実装する場合は、20秒経過後、5秒間隔でポーリングして取得するような手順を推奨します。

解説

  1. エンドポイント

    https://api.mihari.net/v1/users/ユーザー名/detection

  2. メソッド

    GET

  3. ヘッダ

    リクエストヘッダに Authorization を追加し、サインインで取得したIDトークンをセットします。

  4. オプション

    • 名称: "crack"

      • パラメーター:"batchmode"
      • 説明:検出対象の選択。動作モードをオプション指定する。現状、検出対象はcrack、オプションはbatchmodeのみ。省略不可。
      • 使用例:[エンドポイント]?crack=batchmode
    • 名称: "repeat"

      • パラメーター:整数値
      • 説明:検出回数を指定する。省略可。省略時は1。応答メッセージ中のputuris、geturisにおいて、各々指定回数分の要素を持つリストが得られる。
      • 使用例:[エンドポイント]?crack=batchmode&repeat=3
    • 名称:"threshold"

      • パラメーター:0から255までの整数
      • 説明:検出スコアの閾値設定。省略可。省略時は閾値1に設定。
      • 使用例:[エンドポイント]?crack=batchmode&threshold=32
    • 名称:"scale"

      • パラメーター:数値
      • 説明:ひび割れの幅や長さをミリ単位に換算するための縮尺を指定する。画像1ピクセルあたり何ミリかを実数で指定する。本オプションとdistanceオプションの両方とも省略した場合は、幅・長さはピクセル単位になる。負の値など不正な数値を指定した場合は無効。省略可。
      • 使用例:[エンドポイント]?crack=batchmode&scale=0.6
    • 名称:"distance"

      • パラメーター:数値
      • 説明:ひび割れの幅や長さを本オプションと撮影画像に含まれるExif35mm換算焦点距離とで算出する場合に指定する。カメラから被写体までの距離を指定する。単位はミリメートルで、整数で指定する。負の値や小数など不正な数値を指定した場合は無効。対象画像のEXIF情報に35mm換算レンズ焦点距離(FocalLengthIn35mmFilm フィールド)が指定されていない場合は無効。scaleオプションを指定している場合は無効。省略可。
      • 使用例:[エンドポイント]?crack=batchmode&distance=8000
    • 名称:"output"

      • 非推奨:旧システム互換のために存続。出力形式ごとの個別オプション(jpg、dxf、svg)指定を推奨。
      • パラメーター:ファイルタイプ:文字列:"dxf", "svg", "wcmp"の組み合わせ
      • 説明:出力タイプの指定。wcmpは幅長さを元画像に描画したJPEGファイル。パラメーターは、カンマ区切りで複数指定可。本オプションを指定した場合は、出力タイプ別のオプション(jpg、dxf、svg)は無効。省略可。
      • 使用例:[エンドポイント]?crack=batchmode&output=dxf,svg,wcmp
    • 名称:"jpg"

      • パラメーター:描画対象:文字"w"または"s"
      • 説明:ひび割れ検出結果を元画像に重畳表示した画像をJPEGフォーマットで出力する。省略可。
        • "w"は、幅で色分けしたひび割れを描画する。
        • "s"は、ひび割れスコア(ひび割れらしさを点数化した指標)で色分けしたひび割れを描画する。
        • "w"と"s"を同時に指定した場合は無効。
      • 使用例:[エンドポイント]?crack=batchmode&jpg=w
    • 名称:"dxf"

      • パラメーター:ステップ値:数値,最大値:数値,トリム有無:文字"t"
      • 説明:ひび割れ検出結果をDXFフォーマットで出力する。省略可。
        • ステップ値は、指定したひび割れ幅ごとのレイヤーを作成し、ひび割れ結果を区分ごとのレイヤーにそれぞれ出力する。
        • 最大値は、最大値以上の幅のひび割れを全てそのレイヤーに出力する。
        • "t"は、元画像の四隅の位置を表すトリムマークを出力レイヤーに追加する。(省略時はトリムマーク無し)
        • ステップ値と最大値はかならず両方を指定する。一方だけ指定した場合は無効。少数で指定する。
        • 例えば、ステップ値0.2、最大値1.0と指定した場合、出力ファイルに含まれるレイヤー数は6で、0.0以上0.2未満、0.2以上0.4未満、0.4以上0.6未満、0.8以上1.0未満、1.0以上となる。
      • 使用例:[エンドポイント]?crack=batchmode&dxf=0.2,1.0,t
    • 名称:"svg"

      • パラメーター:"レイヤー数","l"
      • 説明:ひび割れ検出結果をSVGフォーマットで出力する。省略可。
        • レイヤー数は、現在1のみ。(省略不可)
        • "l"は、検出したひび割れの脇に、そのひび割れの長さと幅を表す数値を追加する。
      • 使用例:[エンドポイント]?crack=batchmode&svg=1,l
  1. 応答メッセージ

    • 成功時

      • HTTPレスポンスステータスコードは、201です。
      • メッセージ本体は、下記のようなJSONデータです。
          {"message": "accepted",
                 "body": {"puturis": [{"id": "1" "uri": "アップロード先(ファイル名含む)URI"}],
                        "geturis": [
                            {"id": "1", "outputs": [
                                {"type": "dxf", "uri": "ダウンロード先(ファイル名含む)URI"},
                                {"type": "svg", "uri": "ダウンロード先(ファイル名含む)URI"},
                                {"type": "jpg", "uri": "ダウンロード先(ファイル名含む)URI"}
                                ]
                            }]
                          },
                 "timestamp": "日時"}
      • "message":受理された場合は"accepted"
      • "body": 入力用画像のアップロードおよび出力結果のダウンロードに必要なURI
        • "puturis":JOB IDと入力用画像のPUT先URIのセット
        • "geturis":JOB IDとオプションで指定した出力タイプごとの情報セット
          • "outputs": 出力タイプと出力ファイルURIの組で構成
      • "timestamp": 受け付けた日時(ISO8601形式)
    • 失敗時

      • HTTPレスポンスステータスコードは、400です。
      • メッセージ本体は、下記のようなJSONデータです。
          {"message": "Error: エラーメッセージ",
                 "timestamp": "日時"}
  2. リクエストURIの例 https://api.mihari.net/v1/users/(ユーザー名)/detection?crack=batchmode&threshold=24&scale=0.6&unify=10&simplify=10&jpg=w&dxf=0.8,1.0,t&svg=1,l