3.1 ベースURL
基本サービスエンドポイントはこのような記述です。
Copy https://domain.com/openapi/face/v1
Mercury Cloud APIはデータプライバシーを確保するために、HTTPS経由でのAPIのみ提供しています。
domain.com
は、お客様のサービス地域によって異なる場合があります。この情報に関しては、「サービス開始のご連絡」メールで提供されています。
3.2 共通パラメータ
各APIの呼び出しには、いくつかの共通パラメーター、HTTPメソッド、アプリID、アクセスキー、およびシークレットキーが必要です。
GET
と POST
とDELETE
は、Mercury Cloudで使用されるHTTPメソッドです。各APIのメソッドの詳細については、APIリファレンス を参照してください。こちらのHTTPメソッドはAPI認証 の部分でも使用されます。
アプリIDやアクセスキー、およびシークレットキーは、「サービス開始のご連絡」メールで提供されています。 これらは安全な場所に保管し、他人に開示しないでください。 これらはAPI URLの設定とAPI認証トークンの計算時に使用されます。
3.3 API認証
すべてのMercuryAPIは、クライアント検証するためにAPI認証トークンを必要とします。各APIを呼び出す際に、2つのヘッダー(x-dateとAuthorization)が必要です。それらが含まれていない場合、401のHTTPエラーコードが表示されます。
x-dateヘッダー
x-dateヘッダーは、RFC-7231形式でのUTC日付と時刻の形式を使用します。
例:
Copy x - date : Fri , 09 Jul 2021 01 : 51 : 02 GMT
これは「2021-07-09T01:51:02Z」の時間を示しています。x-dateは現地時間ではなく、GMTタイムゾーンの時間であることにご注意ください。
Authorizationヘッダー
Authorizationヘッダーは指定されたAPIパス、HTTPメソッド、アプリID、アクセスキー、およびシークレットキーに基づいて生成されます。特徴DBに関連する一部のAPIではDB IDも必要となります。Authorizationは次のフォーマットに従います。
Copy Authorization: hmac username="{Access_key}", algorithm="hmac-sha256", headers="x-date request-line", signature="{Signature}"
一般的なAuthorizationヘッダー例は次のとおりです。
Copy Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="
hmac username
はアクセスキーです。この例にある005c5acf-5ea9-499c-8d3e-690413f9b5b9
は、お客様のアクセスキーに置換してください。
signature
はHMAC-SHA256によって暗号化され、さらにbase64でエンコードされた文字列です。
Copy signature = encode_base64(hmac_sha256(key={secret_key},message=concat("x-date: ", {x-date}, "/n", {method}, " ", {URL path}, " HTTPS/1.1")))
ステップバイステップで手順を説明します。
まず暗号化される前のmessage
を組み立てます。暗号化前の一般的なmessage
の例は次のとおりです。
Copy x-date : Fri, 09 Jul 2021 01:51:02 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP / 1.1
x-date
はthe x-date header で作成される内容と同様です。
POST
はHTTPメソッドです。使用するAPIのHTTPメソッドと一致させてください。
/openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect
はURLパスです。abc1a8a7-038f-4f9a-b98a-5b602978b135
はアプリIDです。ここはお客様のアプリIDに置換ください。またAPIのURLパスも使用するAPIに置換してください。一部のAPIではDB IDも必要です。
例:
Copy x-date : Fri, 09 Jul 2021 01:51:02 GMT
GET /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/databases/aed37153-16b6-4f19-a479-302049e44000 HTTP / 1.1
aed37153-16b6-4f19-a479-302049e44000
はDB IDです。
シークレットキーblFWSvhp9pRz2JnRHnfvkFeAuApClhKg
を使用して、最初に作成した以下のメッセージを暗号化にします。
Copy x-date : Fri, 09 Jul 2021 01:37:00 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP / 1.1
以下の内容が出力されます。
Copy 91427a38788c301667c604846b6011c550258230b69338de7598313b3d3b8be6
最後にbase64でエンコードすると、signature
は次のように完成されます。
Copy kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y=
このsignature
を使用すると、上記と同じようなのAuthorizationヘッダーが完成されます。
Copy Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="
これで、x-date Header とAuthorization Header を利用して、/openapi/face/v1/{app_id}/detect
のAPI呼び出しができます。
Copy curl -X POST -d {} 'https://domain.com/openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect' \
-H 'x-date: Fri, 09 Jul 2021 01:37:00 GMT' \
-H 'Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="'
Python
Copy import base64
import datetime
import hashlib
import hmac
import urllib . parse
def generate_authorization_headers ( access_key , secret_key , url , http_method ):
RFC7231_FORMAT = ' %a , %d %b %Y %H:%M:%S GMT'
xdate = datetime . datetime . utcnow (). strftime (RFC7231_FORMAT)
url_path = urllib . parse . urlparse (url). path
signature = 'x-date: %s \n %s %s HTTP/1.1' % (xdate , http_method . upper (), url_path)
crypto = hmac . new (secret_key. encode ( 'utf-8' ), signature. encode ( 'utf-8' ), hashlib.sha256)
hmac_signature = base64 . b64encode (crypto. digest ()). decode ( 'utf-8' )
authorization = '''hmac username="%s", algorithm="hmac-sha256", headers="x-date request-line", signature="%s"''' % (access_key, hmac_signature)
return {
"x-date" : xdate ,
"Authorization" : authorization
}
JavaScript
Copy //crypto-jsが必要です。 詳細はhttps://www.npmjs.com/package/crypto-jsを参照してください。
function generate_authorization_headers (access_key , secret_key , url , http_method) {
var today = new Date ();
var xdate = today .toGMTString ();
var reg = /. +? \:\/\/. +? (\/. +? )(?:# | \? |$ )/ ;
var url_path = reg .exec (url)[ 1 ];
var signature = "x-date: " + xdate + "\n" + http_method + " " + url_path + " HTTP/1.1" ;
var hmac_signature = CryptoJS .HmacSHA256 (signature , secret_key) .toString ( CryptoJS . enc .Base64);
var authorization = "hmac username=\"" + access_key + "\", algorithm=\"hmac-sha256\", headers=\"x-date request-line\", signature=\"" + hmac_signature + "\"";
return "-H 'x-date: " + xdate + "' -H 'Authorization: " + authorization + "'" ;
}
Kotlin
Copy import java.text.SimpleDateFormat
import java.util.*
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.net.URL
fun generate_authorization_headers (
access_key: String ,
secret_key: String ,
url: String ,
http_method: String ): Pair < String , String > {
val rfc7231 = SimpleDateFormat ( "EEE, dd MMM yyyy HH:mm:ss 'GMT'" , Locale.US). apply {
isLenient = false
timeZone = TimeZone. getTimeZone ( "UTC" )
}
val xDate = rfc7231. format ( Date ())
val url_path = URL (url). getPath ()
val encodeData = "x-date: $xDate\n$http_method $url_path HTTP/1.1"
val sha256Hmac = Mac. getInstance ( "HmacSHA256" )
val secretKey = SecretKeySpec (secret_key. toByteArray (), "HmacSHA256" )
sha256Hmac. init (secretKey)
val signature = Base64. getEncoder (). encodeToString (sha256Hmac. doFinal (encodeData. toByteArray ()))
val authorization = "hmac username=\"${access_key}\", algorithm=\"hmac-sha256\", headers=\"x-date request-line\", signature=\"${signature}\""
return Pair (xDate,authorization)
}
3.5 SwaggerHubで"Try it out"
SwaggerHubでは、「Try it out」ボタンを使用してブラウザーから直接API呼び出しをテストできるインタラクティブな方法を提供しています。Mercury Cloud Interactive APIドキュメントでは、この機能を使用する前に特別な認証を行うことが必要です。ここでは、Mercury Cloud InteractiveAPIドキュメントの「Try it out」機能を使用するための方法を解説します。
ヘッダー作成ツールで、x-dateヘッダー とAuthorizationヘッダー を準備します。
3.5.2 サーバーを選択
"Servers"のドロップダウンリストをクリックして、サービスエリアに応じたサーバーを選択してください。
サーバーリストの右側にある「Authorize」ボタンをクリックしてください。
次の画面が表示されます。Authorizationヘッダーを「Value」に貼り付けて、「Authorize」ボタンをクリックしてください。
これでAuthorizationヘッダーが設定されました。再認証するには「Logout」ボタンをクリックして、上記の手順をやり直してください。
Authorizationヘッダーは時間に依存するため、APIを呼び出す度に再承認する必要があります。
3.5.4 パラメータを入力して試してみてください
これでAPI呼び出しを試すことができます。 List Feature DatabaseのAPIを例として試してみます。
「Try it out」ボタンをクリックすると「Execute」ボタンが表示されます。x-dateとapp_idパラメータを入力し、「Execute」ボタンをクリックしてください。
APIのレスポンスおよびいくつかの関連情報が表示されます。