クラウド認識 APIs の概要
API 一覧
REST API インターフェースプロトコルと認証メカニズム
CRS API は標準的な HTTP REST 通信標準に準拠しています。
Http ヘッダー
Authorization: <APIKey で取得したトークンを入力>
Http リクエストパラメータは、2種類に分けられます:
共通パラメータ（認証方式によって異なる組み合わせで使用されます）:
- appId
- timestamp（Long 長整数型：1970年1月1日00:00:00 UTCからの経過ミリ秒数）
- apiKey
- signature（リクエスト署名、トークン認証方式と二者択一）
CRS API パラメータ: API 固有のパラメータ
API ドキュメントでは認証用共通パラメータは記述しません
API Key 認証
認証方式は2種類あります:
トークンベース認証
Http ヘッダー Authorization にトークンを含めます。共通パラメータは:
- appId
署名認証
Http ヘッダー 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": //statusCode が 0 の場合のみ result あり。エラー時は結果フィールドは空
}
上記の例に示すように、これは正常に返されたターゲット画像の詳細構造です。ターゲット画像には以下の属性が含まれます:
| 属性 | 説明 |
|---|---|
| targetId | ターゲット画像の一意な ID |
| trackingImage | デバイス側画像トラッキング用に処理されたグレースケール画像の base64 エンコード |
| name | ターゲット画像名 |
| size | 画像サイズ。アプリケーションで仮想コンテンツを重ねる際の実際のサイズ |
| meta | ユーザー関連データ。ファイル、テキスト、URL が可能。base64 エンコードが必要 |
| type | "ImageTarget" |
| active | 有効化されたターゲット画像のみが認識可能。無効化後は認識されない |
| trackableRate | トラッキング難易度評価、値が小さいほど良い |
| detectableRate | 認識総合難易度評価、値が小さいほど良い |
| detectableDistinctiveness | 認識識別難易度評価、値が小さいほど良い |
| detectableFeatureCount | 認識特徴面での難易度評価、値が小さいほど良い |
| trackableDistinctiveness | トラッキング識別難易度評価、値が小さいほど良い |
| trackableFeatureCount | トラッキング特徴面での難易度評価、値が小さいほど良い |
| trackableFeatureDistribution | トラッキング特徴分布難易度評価、値が小さいほど良い |