すべてのプロダクト
Search
ドキュメントセンター

ID Verification:初期化

最終更新日:Nov 09, 2025

このトピックでは、Initialize 操作を呼び出して認証リクエストを開始する方法について説明します。

認証リクエストの開始

  • 操作: Initialize

  • リクエストメソッド: HTTPS POST

  • 説明: 各認証フローを開始する前に、この操作を呼び出して transactionId を取得できます。この ID は、認証リクエスト内の API 操作をリンクします。

  • QPS 制限: この API は、排他的な秒間クエリ数 (QPS) 制限の対象となります。詳細については、「ID Verification サーバーサイド API の QPS 制限」をご参照ください。

  • エンドポイント:

    説明

    内部ネットワークは、同じリージョン内の Alibaba Cloud プロダクト間のプライベート通信ネットワークです。アプリケーションサーバーが Alibaba Cloud リージョンにデプロイされている場合、内部エンドポイントを使用して ID Verification サービスにアクセスできます。これにより、より安全で安定したネットワーク接続が提供されます。

    中国 (香港)

    • パブリックエンドポイント: cloudauth-intl.cn-hongkong.aliyuncs.com

    • 同一リージョン内の内部エンドポイント: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

オンラインでのテストと統合

説明

デバッグと統合を行う前に、ドキュメント「OpenAPI Explorer を使用してサーバーサイド API 操作をデバッグおよび統合する」をお読みください。このドキュメントでは、OpenAPI プラットフォームで API 操作を呼び出す方法と、SDK およびそのサンプルコードを取得する方法について説明しています。

この操作は OpenAPI Explorer で直接実行してテストできます。 また、この操作の SDK サンプルコード を生成することもできます。

リクエストパラメーター

名前

タイプ

必須

説明

ProductCode

String

はい

使用するプロダクトソリューション。有効な値は FACE_LIVENESS のみです。

FACE_LIVENESS

SceneCode

String

いいえ

認証シナリオのカスタム ID。この ID を使用して、コンソールで関連レコードをクエリできます。ID は最大 10 文字で、文字、数字、アンダースコア (_) を使用できます。

1234567890

MerchantBizId

String

はい

カスタムの一意なビジネス識別子。問題の追跡やトラブルシューティングに使用できます。識別子は最大 32 文字で、文字と数字を含めることができます。識別子が一意であることを確認してください。

説明

Alibaba Cloud サーバーは、この値の一意性をチェックしません。追跡を改善するために、このフィールドの一意性を確保することを強く推奨します。

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

はい

MetaInfo 環境パラメーター。実際の環境では、JS ファイル内の getMetaInfo() 関数を呼び出してこのパラメーターを取得する必要があります。詳細については、「Android 統合」をご参照ください。

説明

戻り値を変更しないでください。そのまま渡してください。

{
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "ios",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

MerchantUserId

String

はい

特定のユーザーのカスタムユーザー ID または別の識別子 (携帯電話番号やメールアドレスなど)。ハッシュ化するなどして、この値を事前に非機密化することを強く推奨します。

123456789

SecurityLevel

String

いいえ

認証プロセスの異なるセキュリティレベルを表すモード。有効な値:

  • 01: 標準モード。このモードは、デバイス情報の収集に制限がある低脅威のシナリオにのみ適用されます

  • 02: 安全モード。比較的厳格なモード (デフォルト)

    説明

    安全モードでは、SDK の新しい Device Guard モジュールを使用して、顔スキャン環境とデバイスのセキュリティを識別します。これにより、インジェクション攻撃の迎撃が効果的に強化されます。このモードを選択することを強く推奨します。

02

Model

String

いいえ

実行する生体検知のタイプ:

  • LIVENESS (デフォルト): 瞬きアクションによる生体検知。

  • PHOTINUS_LIVENESS: 瞬きアクションによる生体検知とカラフルな生体検知によるデュアル検知。

  • PHOTINUS_FAR_NEAR_LIVENESS: 瞬きアクション + 遠近 + カラフルな生体検知。

    (App SDK または App SDK に基づく Flutter 統合でのみサポートされます)

説明
  • サポートされている SDK バージョンについては、「SDK リリースノート」をご参照ください。

  • PC はカラフルな生体検知によるデュアル検知をサポートしていません。

PHOTINUS_LIVENESS

DocVideo

String

いいえ

検証ビデオを保存するかどうかを指定します。

  • N: いいえ (デフォルト)。

  • Y: 認証中にユーザーの顔スキャンプロセスのビデオ (1〜2 秒のビデオファイル) が収集され、クエリ API 操作を通じて返されます。

説明

ビデオファイルはサイズが大きいため、ネットワークが不安定な場合、システムは不可欠な認証イメージの送信を優先するためにビデオファイルを破棄することがあります。

N

CallbackUrl

String

いいえ

認証結果の Webhook アドレス。コールバックリクエストメソッドはデフォルトで GET です。Webhook アドレスは https で始まる必要があります。認証が完了すると、プラットフォームはこのアドレスにコールバックを送信し、次のフィールドを自動的に追加します:

  • transactionId

  • passed

  • subcode

警告
  • この値は、API 操作が呼び出される前にアクセシビリティがチェックされます。提供されたアドレスがインターネットからアクセスできない場合、400 エラーが返されます。

  • コールバックは認証完了直後に実行されますが、ネットワークの問題により遅延する可能性があります。まずクライアント側で認証完了通知を受け取り、次にクエリ API 操作を呼び出して認証の詳細を取得することをお勧めします。

https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

CallbackToken

String

いいえ

生成するセキュリティトークン。リプレイ防止および改ざん防止チェックに使用されます。

このパラメーターを設定すると、CallbackToken フィールドが CallbackUrl コールバックに含まれます。

NMjvQanQgplBSaEI0sL86WnQplB

AppQualityCheck

String

いいえ

厳格な顔品質チェックを有効にするかどうかを指定します:

  • Y: はい。(デフォルト)

  • N: いいえ。

重要
  • この構成には、クライアントサイド SDK からのサポートが必要です。この機能を有効にしても、クライアントサイド SDK に顔品質検出モジュールが統合されていない場合、この構成は無効として扱われます。

  • クライアントサイド SDK はバージョン 1.2.5 以降である必要があります。

N

応答パラメーター

名前

タイプ

説明

HTTP ステータスコード

Integer

HTTP ステータスコード。

200

HTTP 本文

RequestId

String

リクエスト ID。

130A2C10-B9EE-4D84-88E3-5384FF03****

Code

String

応答コード

Success

Message

String

応答コードの詳細な説明。

success

Result.TransactionId

String

認証プロセス全体のユニークな識別子。このフィールドは、課金統計および CheckResult API 操作リクエストの開始に使用されます。

重要
  • リクエスト中にエラー (無効なパラメーターなど) が発生した場合、TransactionId は返されません。

  • サーバー上で TransactionId をビジネスプロセス ID にバインドして保存することをお勧めします。CheckResult を呼び出すときは、サーバーのストレージからこの認証 ID を取得して結果クエリを開始します。

  • TransactionId または TransactionUrl を正常に取得した後、30 分以内に認証を完了する必要があります。この期間を過ぎると、ID または URL は自動的に有効期限切れとなり、認証に使用できなくなります。

hksb7ba1b28130d24e015d6********

リターンコード

HTTP ステータスコード

コード

メッセージ

200

Success

リクエストは成功しました。

400

MissingParameter

パラメーターを空にすることはできません。

InvalidParameter

無効なパラメーター。

403

Forbidden.RAMUserAccessDenied

RAM ユーザーに AliyunAntCloudAuthFullAccess 権限を付与する必要があります。詳細については、「RAM ユーザーにサービスへのアクセスを承認する」をご参照ください。

Forbidden.AccountAccessDenied

ID Verification を有効にし、アカウントに支払い遅延がないことを確認してください

Throttling.Api

スロットリングにより API リクエストがブロックされました。

500

InternalError

内部システムエラー。トラブルシューティングのためにエンジニアにフィードバックを提供してください。