3 APIの呼び出し方法

Mercury Cloud OpenAPIの呼び出し方法について記載しています。

3.1 ベースURL

基本サービスエンドポイントはこのような記述です。

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日付と時刻の形式を使用します。

例：

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は次のフォーマットに従います。

Authorization: hmac username="{Access_key}", algorithm="hmac-sha256", headers="x-date request-line", signature="{Signature}"

一般的なAuthorizationヘッダー例は次のとおりです。

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でエンコードされた文字列です。

signature = encode_base64(hmac_sha256(key={secret_key},message=concat("x-date: ", {x-date}, "/n", {method}, " ", {URL path}, " HTTPS/1.1")))

ステップバイステップで手順を説明します。

まず暗号化される前のmessageを組み立てます。暗号化前の一般的なmessageの例は次のとおりです。

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も必要です。

例：

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を使用して、最初に作成した以下のメッセージを暗号化にします。

x-date: Fri, 09 Jul 2021 01:37:00 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP/1.1

以下の内容が出力されます。

91427a38788c301667c604846b6011c550258230b69338de7598313b3d3b8be6

最後にbase64でエンコードすると、signatureは次のように完成されます。

kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y=

このsignatureを使用すると、上記と同じようなのAuthorizationヘッダーが完成されます。

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呼び出しができます。

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="'

3.4 ヘッダー作成ツールサンプル

Python

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

//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

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」機能を使用するための方法を解説します。

3.5.1 ヘッダーを準備

ヘッダー作成ツールで、x-dateヘッダーとAuthorizationヘッダーを準備します。

3.5.2 サーバーを選択

"Servers"のドロップダウンリストをクリックして、サービスエリアに応じたサーバーを選択してください。

サーバーを選択

3.5.3 Authorizationヘッダーで認証

サーバーリストの右側にある「Authorize」ボタンをクリックしてください。

Authorize

次の画面が表示されます。Authorizationヘッダーを「Value」に貼り付けて、「Authorize」ボタンをクリックしてください。

Authorizationを有効

これでAuthorizationヘッダーが設定されました。再認証するには「Logout」ボタンをクリックして、上記の手順をやり直してください。

Authorizationヘッダーは時間に依存するため、APIを呼び出す度に再承認する必要があります。

Authorizationを取り消し

3.5.4 パラメータを入力して試してみてください

これでAPI呼び出しを試すことができます。 List Feature DatabaseのAPIを例として試してみます。

Try it outボタン

「Try it out」ボタンをクリックすると「Execute」ボタンが表示されます。x-dateとapp_idパラメータを入力し、「Execute」ボタンをクリックしてください。

Execute

APIのレスポンスおよびいくつかの関連情報が表示されます。

実施結果