Cloud Recognition APIs の概要

API 一覧

REST API インターフェースプロトコルと認証メカニズム

CRS API は標準 HTTP REST 転送標準に従います。

Http Header

Authorization: <APIKey で取得した Token を入力>

Http リクエストパラメータは 2 種類に分かれます。

共通パラメータ（以下をすべて含みます。認証方式により使用する組み合わせが異なります）:
- appId
- timestamp（Long 長整数: 1970 年 1 月 1 日 00:00:00 UTC から経過したミリ秒数）
- apiKey
- signature（リクエスト署名。token 方式認証との二者択一）
CRS API パラメータ: API 自身のパラメータ

API ドキュメントでは、認証用の共通パラメータを今後説明しません

API Key 認証

認証方式は 2 種類に分かれます。

Token ベース認証

Http header Authorization に Token を含めます。共通パラメータは次のとおりです。

appId

署名認証

Http header Authorization は使用しません。

共通パラメータには signature 署名情報が含まれます。画像を除くすべてのパラメータが署名計算に含まれます。

appId
timestamp
apiKey
signature

署名計算の詳細なアルゴリズムとコードについては、API Key 署名方法を参照してください。

使用例とプロパティ解析

API 使用例

ここでは、API インターフェースを呼び出してターゲット画像を作成する例を通じて、開発者が CRS API のリクエストプロセス、ターゲット画像のプロパティ構造、インターフェースの入出力を理解できるようにします。

本番環境でターゲット画像を作成する前には、より多くの検証が必要です。具体的には、ベストプラクティスを参照して新しいターゲット画像を作成してください。

リクエスト例

test-target.jpg というターゲット画像ファイルを追加します。ターゲット画像を作成するとき、画像ファイルは base64 エンコードする必要があります。

API ドキュメントではリクエストパラメータを詳しく説明します。API - ターゲット画像を作成を参照し、画像ファイルを base64 エンコードして API をリクエストしてください。

POST /targets HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "active":"1",
    "name":"easyar",
    "size":"5",
    "meta":"496fbbabc2b38ecs3460a...",
    "type":"ImageTarget",
    "timestamp": 1514736000000,
    "apiKey": "8b485c648c3056e79c2a85ee9b51f9dc",
    "appId": "C:CN1:f9f903c36da8bd64d71d491077bba...",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

レスポンス例

HTTP/1.1 200 OK
Content-Type: application/json
{
    "statusCode": 0,
    "result": {
        "targetId":"e61db301-e80f-4025-b822-9a00eb48d8d2",
        "trackingImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM..."，
        "name": "easyar",
        "size": "5",
        "meta": "496fbbabc2b38ecs3460a...",
        "type": "ImageTarget",
        "modified":1514735000000
        "active":"1"，
        "trackableRate": 0,
        "detectableRate": 0,
        “detectableDistinctiveness”：0,
        "detectableFeatureCount": 0,
        "trackableDistinctiveness": 0,
        "trackableFeatureCount": 0,
        "trackableFeatureDistribution": 0,
        "trackablePatchContrast": 0,
        "trackablePatchAmbiguity": 0
    },
    "timestamp": 1514736000000
}

レスポンス形式

レスポンスはすべて統一形式を使用します。以下は例です。

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //result は statusCode が 0 の場合のみ存在します。エラーが発生した場合、結果フィールドは空です
}

上の例に示すように、これはターゲット画像詳細構造の通常の戻り値です。1 つのターゲット画像には次のプロパティが含まれます。

プロパティ	説明
targetId	ターゲット画像の一意の Id
trackingImage	処理後のグレースケール画像の base64 エンコード。デバイス側の画像トラッキングに使用されます
name	ターゲット画像名
size	画像サイズ。アプリ内で仮想コンテンツを重ねる実用的なサイズ
meta	ユーザー関連データ。ファイル、テキスト、url が可能で、base64 エンコードが必要です
type	"ImageTarget"
active	有効化されたターゲット画像のみ認識できます。無効化後は認識されません
trackableRate	トラッキング難易度スコア。小さいほど良い
detectableRate	認識総合難易度スコア。小さいほど良い
detectableDistinctiveness	認識の識別性難易度スコア。小さいほど良い
detectableFeatureCount	認識特徴の難易度スコア。小さいほど良い
trackableDistinctiveness	トラッキングの識別性難易度スコア。小さいほど良い
trackableFeatureCount	トラッキング特徴の難易度スコア。小さいほど良い
trackableFeatureDistribution	トラッキング特徴分布の難易度スコア。小さいほど良い

エラーコード

Cloud recognition APIs エラーコード説明

Table of Contents