OpenSearch:OpenSearch API V3 の署名方法

OpenSearch は、各アクセスリクエストを認証します。 このサービスは、AccessKey ペアに基づいて対称暗号化を実装し、ユーザーの ID を検証します。 各 AccessKey ペアは、AccessKey ID と AccessKey シークレットで構成されます。

AccessKey ID と AccessKey シークレットは、Alibaba Cloud によってユーザーに正式に発行されます。 Alibaba Cloud 国際サイト (alibabacloud.com) で AccessKey ペアをリクエストおよび管理できます。 AccessKey ID は、ユーザー ID を検証するために使用されます。

AccessKey シークレットは、署名文字列を暗号化し、サーバー上で署名文字列を検証するために使用されます。 AccessKey シークレットは厳重に管理する必要があります。

• 高度なアプリケーション

• 標準アプリケーション

OpenSearch API V3 は、HTTP プロトコルのみをサポートしています。

• データを検索するには、HTTP GET リクエストを送信する必要があります。

• データを送信するには、HTTP POST リクエストを送信する必要があります。

HTTP リクエストの Authorization ヘッダーに署名文字列を追加する必要があります。 これは、リクエストが認証されていることを示します。 HTTP リクエストには、他の必要なヘッダーも含まれている必要があります。 このトピックの「例」セクションでは、ヘッダーの例を示します。

Content-Md5、Content-Type、Date、OpenSearch 固有の HTTP ヘッダーなど、すべてのリクエストヘッダーは、署名計算に使用する必要があります。後続の署名対象文字列の "Authorization:OPENSEARCH " にある OPENSEARCH の後には、スペースを追加する必要があります。

"Authorization: OPENSEARCH " + AccessKeyId + ":" + Signature
Signature = base64(hmac-sha1(AccessKeySecret,
            VERB + "\n"
            + Content-Md5 + "\n"
            + Content-Type + "\n"
            + Date + "\n"
            + CanonicalizedOpenSearchHeaders
            + CanonicalizedResource))

RFC 2104 で定義されている string-to-sign の HMAC 値を計算する

• RFC 2104 で定義されている HMAC-SHA1 メソッドを使用して、署名文字列を計算します。

• 署名文字列は、UTF-8 でエンコードする必要があります。

• 中国語の文字を含む署名文字列は、最初に UTF-8 でエンコードする必要があります。 エンコードされた署名文字列は、AccessKeySecret パラメーターと共に使用されて、最終的な署名文字列が計算されます。

• 署名文字列の計算に使用されるパラメーターは、上記のサンプルコードと同じ方法でソートする必要があります。

• リクエストヘッダーの値は、署名の計算に指定された値と同じである必要があります。

• Content-Md5、Content-Type、Date、CanonicalizedOpenSearchHeaders、Authorization パラメーターをリクエストヘッダーとして追加することをお勧めします。 必要なリクエストヘッダーのみを指定すると、エラーが発生する可能性があります。

• すべてのリクエストヘッダーは、署名の計算に使用される必要があります。

• リクエストヘッダーの値は、署名の計算に指定された値と同じである必要があります。

• Content-Md5、Content-Type、Date、CanonicalizedOpenSearchHeaders、Authorization パラメーターをリクエストヘッダーとして追加することをお勧めします。 必要なリクエストヘッダーのみを指定すると、エラーが発生する可能性があります。

• すべてのリクエストヘッダーは、署名の計算に使用される必要があります。

CanonicalizedOpenSearchHeaders パラメーターには、X-Opensearch- というプレフィックスが付いたすべての OpenSearch 固有の HTTP ヘッダーが含まれます。 他の HTTP ヘッダーはこのセクションには関係ありません。

1. X-Opensearch- というプレフィックスが付いた OpenSearch 固有の HTTP ヘッダーの値を指定します。 たとえば、完全な HTTP ヘッダーは X-Opensearch-Nonce : 155108********** です。 ヘッダーの値 (例: 155108**********) は、10 桁のタイムスタンプと 100000 ～ 999999 の 6 桁のランダム値で構成されます。次に、値が空のすべての OpenSearch 固有の HTTP ヘッダーを省略します。

2. 残りのすべての OpenSearch 固有の HTTP ヘッダーをアルファベット順にソートします。

3. ソートされた HTTP ヘッダーの名前の大文字を小文字に変換します。 たとえば、X-Opensearch-Nonce : 155108********** を x-opensearch-nonce : 155108********** に変換します。

4. 各ヘッダーとその値の間のデリミタの両側のスペースをすべて削除します。 たとえば、元の HTTP ヘッダーは x-opensearch-nonce : 155108********** です。 スペースが削除されると、HTTP ヘッダーは x-opensearch-nonce:155108********** になります。

5. 各ヘッダーと値のペアを 1 つの項目と見なします。 \n デリミタを使用してすべての項目を連結し、最終的な CanonicalizedOpenSearchHeaders 文字列を形成します。 \n デリミタは、最後の項目にも追加する必要があります。

CanonicalizedResource 文字列を作成する

• 署名文字列は、UTF-8 でエンコードする必要があります。 中国語の文字を含む署名文字列は、最初に UTF-8 でエンコードする必要があります。 エンコードされた署名文字列は、AccessKeySecret パラメーターと共に使用されて、最終的な署名文字列が計算されます。

• データを検索するリクエストの CanonicalizedResource 文字列の形式は、path + ? + query です。

• データを送信するリクエストの CanonicalizedResource 文字列の形式は、path です。

path 文字列を作成する

path 文字列を作成するには、元の文字列をエンコードし、%2F をスラッシュ (/) に置き換え、app_schema_demo をアプリケーションの名前に置き換えます。 次のリストは、4 つの一般的な path 文字列を示しています。

• データを検索するリクエストの path 文字列: /v3/openapi/apps/app_schema_demo/search。

• 候補に基づいてデータを検索するリクエストの path 文字列: /v3/openapi/suggestions/suggestion_name/actions/search。

• アプリケーションを使用してデータを検索するリクエストの path 文字列: /v3/openapi/apps/appid。 この場合、appid を検索に使用するアプリケーションの ID に置き換え、認証のために Authorization ヘッダーを指定する必要があります。 リクエストパラメーターを指定する必要はありません。

• データを送信するリクエストの path 文字列: /v3/openapi/apps/app_schema_demo/tab/actions/bulk。 この場合、tab をアプリケーションでデータを受信するために使用するテーブルの名前に置き換える必要があります。

query 文字列は、リクエストパラメーターで構成されます。 パラメーターは、キーと値のペアの形式で指定されます。 CanonicalizedResource 文字列の query 文字列を作成するには、次の手順を実行します。

1. 使用する各リクエストパラメーターに値を割り当て、値が空のリクエストパラメーターを省略します。 値が空のリクエストパラメーターは、署名の計算には使用されません。

2. リクエストパラメーターを、最初に key で、次に value でアルファベット順にソートします。

3. RFC 3986 標準に基づいて、リクエストパラメーターの key と value をエンコードします。 次に、等号 (=) を使用して、エンコードされた各リクエストパラメーターのキーと値を連結します。

4. アンパサンド (&) を使用して、エンコードされたリクエストパラメーターを連結し、値を query 文字列として保存します。

5. path 文字列と query 文字列を使用して、path + ? + query の形式で最終的な CanonicalizedResource 文字列を形成します。 CanonicalizedResource 文字列の例: /v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson。

   • CanonicalizedResource 文字列の例には、次のリクエストパラメーターとその値が含まれています。

     • fetch_fields=name

   • CanonicalizedResource 文字列の例には、次のクエリパラメーターと句が含まれています。 最初の部分はクエリパラメーターを示し、2 番目の部分はクエリ句とその他の関連句を示します。

     • query=query=name:'document'&&sort=id&&config=format:fulljson

Authorization ヘッダーの作成方法については、このトピックの「Authorization ヘッダーの値を計算する」セクションをご参照ください。 たとえば、ユーザーの AccessKey ID が LTAI**************** で、署名文字列が 1P7tfE**** であるとします。 次の Python 3 コードの例は、Authorization ヘッダーを作成します。

headers['Authorization'] = 'OPENSEARCH ' + 'LTAI****************' + ':' + '1P7tfE****'

たとえば、リクエストのヘッダーとパラメーター、およびリクエストメソッドは次のように構成されます。

• Authorization: OPENSEARCH LTAI****************:1P7tfE****。

• AccessKeySecret: yourAccessKeySecret。

• リクエストメソッド: GET。

• Content-MD5: サンプルリクエストはデータを検索するために使用されるため、このパラメーターは空のままです。

• Content-Type: application/json。

• Date: 2019-02-25T10:09:57Z。

• CanonicalizedOpenSearchHeaders: x-opensearch-nonce:15510****1704。

• CanonicalizedResource: /v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson。

署名文字列の計算例

• この例では、HMAC 値と Base64 エンコード形式を使用して署名文字列を計算します。

Python 3 コードの例:

import hmac
import base64
signature_string = '\n'.join(['GET',
                              '',
                              'application/json',
                              '2019-02-25T10:09:57Z',
                              'x-opensearch-nonce:1551089397451704',
                              '/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson'])
signature_hmac = hmac.new('yourAccessKeySecret'.encode('utf-8'), signature_string.encode('utf-8'), 'sha1')
signature = base64.b64encode(signature_hmac.digest())
#日本語のコメントを追加
#署名文字列を生成

たとえば、ユーザーの AccessKey シークレットが yourAccessKeySecret であるとします。 上記の計算方法を使用して計算された最終的な署名文字列は 1P7tfE**** です。

リクエスト文字列の形式は、host + CanonicalizedResource 文字列です。

HTTP リクエストの Authorization ヘッダーに署名文字列を追加する必要があります。 これは、リクエストが認証されていることを示します。 HTTP リクエストには、前のセクションで説明した他の必要なヘッダーも含まれている必要があります。 リクエスト文字列では、host は OpenSearch API のエンドポイントを指定します。

• データを検索するリクエストのリクエスト文字列: http://host/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27%26%26sort%3Did%26%26config%3Dformat%3Afulljson。

• 候補に基づいてデータを検索するリクエストのリクエスト文字列: http://host/v3/openapi/apps/{appName}/suggest/{suggestName}/search?hits=10&query=%E6%A0%87%E9%A2%98。

• アプリケーションを使用してデータを検索するリクエストのリクエスト文字列: http://host/v3/openapi/apps/120001234。 この場合、appid を検索に使用するアプリケーションの ID (例: 120001234) に置き換え、認証のために Authorization ヘッダーを指定する必要があります。 リクエストパラメーターを指定する必要はありません。

• データを送信するリクエストのリクエスト文字列: http://host/v3/openapi/apps/app_schema_demo/tab/actions/bulk。 送信されるデータは、リクエストボディで指定する必要があります。

{
  "name": "app_schema_demo",
  "type": "standard",
  "schema": {
    "indexes": {
      "search_fields": {
        "id": {
          "fields": [
            "id"
          ]
        },
        "name": {
          "fields": [
            "name"
          ],
          "analyzer": "chn_standard"
        },
        "phone": {
          "fields": [
            "phone"
          ],
          "analyzer": "fuzzy"
        },
        "int_arr": {
          "fields": [
            "int_arr"
          ]
        },
        "literal_arr": {
          "fields": [
            "literal_arr"
          ]
        },
        "cate_id": {
          "fields": [
            "cate_id"
          ]
        }
      },
      "filter_fields": [
        "id",
        "int_arr",
        "literal_arr",
        "float_arr",
        "cate_id"
      ]
    },
    "tables": {
      "tab": {
        "name": "tab",
        "fields": {
          "id": {
            "name": "id",
            "type": "INT",
            "primary_key": true
          },
          "name": {
            "name": "name",
            "type": "TEXT",
            "primary_key": false
          },
          "phone": {
            "name": "phone",
            "type": "SHORT_TEXT",
            "primary_key": false
          },
          "int_arr": {
            "name": "int_arr",
            "type": "INT_ARRAY",
            "primary_key": false
          },
          "literal_arr": {
            "name": "literal_arr",
            "type": "LITERAL_ARRAY",
            "primary_key": false
          },
          "float_arr": {
            "name": "float_arr",
            "type": "FLOAT_ARRAY",
            "primary_key": false
          },
          "cate_id": {
            "name": "cate_id",
            "type": "INT",
            "primary_key": false
          }
        },
        "primary_table": true
      }
    },
    "route_field": null
  },
  "data_sources": [],
  "first_ranks": {},
  "second_ranks": {},
  "summary": [],
  "fetch_fields": [
    "id",
    "name",
    "phone",
    "int_arr",
    "literal_arr",
    "float_arr",
    "cate_id"
  ],
  "quota": {
    "qps": 6,
    "doc_size": 0.3
  }
}
// アプリケーションスキーマのテンプレート