XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

788

リビジョン

1

Ratification Status（批准ステータス）

未批准

拡張機能とバージョンの依存関係

XR_EXT_future

最終更新日

2025-12-18

IP ステータス

既知の IP 申し立てはありません。

寄与者

John Ullman（Google）
Ben King（Google）
Nihav Jain（Google）
Jared Finder（Google）

概要

この拡張機能により、アプリケーションが Google Cloud APIs の認証情報を提供できるようになり、Google Cloud ベースの拡張機能を使用できるようになります。デベロッパーは、Google Cloud コンソール（https://console.cloud.google.com/）を使用して、アプリの Google Cloud プロジェクトを作成する必要があります。この拡張機能には、拡張機能 XR_EXT_future が必要です。

開発中、アプリケーションは拡張機能 XR_EXT_debug_utils を使用して、Google Cloud 設定の問題をデバッグできます。アプリケーションにデバッグ メッセンジャーがあり、アプリケーションに代わって Google Cloud にリクエストを送信するときに、実行時に対応可能なエラーが発生した場合、実行時はエラー メッセージとともにメッセンジャーのコールバックを呼び出します。この場合、デベロッパーはエラー メッセージと利用可能なすべてのドキュメントを参照し、Google Cloud APIs を使用するようにアプリケーションと Google Cloud プロジェクトが適切に設定されていることを確認する必要があります。ランタイムは、メッセージ タイプ XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT、重大度 XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT、messageId「GoogleCloudError」を使用する必要があります。

認証

XrGoogleCloudAuthInfoBaseHeaderANDROID 構造体は次のように定義されます。

typedef struct XrGoogleCloudAuthInfoBaseHeaderANDROID {
    XrStructureType    type;
    const void*        next;
} XrGoogleCloudAuthInfoBaseHeaderANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。

この構造は API で直接使用されませんが、認証情報を提供するために xrSetGoogleCloudAuthAsyncANDROID で使用できる他の構造によって拡張されます。

有効な使用方法（暗黙的）

XrGoogleCloudAuthInfoApiKeyANDROID 構造体は次のように定義されます。

typedef struct XrGoogleCloudAuthInfoApiKeyANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        apiKey;
} XrGoogleCloudAuthInfoApiKeyANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • apiKey は、API キーを表す文字列へのポインタです。

この構造体が xrSetGoogleCloudAuthAsyncANDROID に渡される場合、apiKey メンバーはスペースや制御文字を含まない空でない ASCII 文字列でなければなりません。そうでない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

apiKey は、さらに次の条件を満たしている必要があります。

  • Google Cloud プロジェクト用に生成された有効な API キーである必要があります。
  • Google Cloud プロジェクトで、関連する Google Cloud API（依存する拡張機能で指定）を有効にする必要があります。
  • API キーに制限がある場合、制限で関連する Google Cloud API とアプリケーションが許可されている必要があります。

それ以外の場合、xrSetGoogleCloudAuthAsyncANDROID の呼び出しは成功しますが、クラウド認証に依存する関数の呼び出しはすべて、それらの関数を定義する拡張機能のクラウド障害に関するドキュメントに記載されているとおりに動作します。関数が失敗を報告でき、アプリが XrGoogleCloudAuthErrorResultANDROID をその関数の出力パラメータにチェーンする場合、ランタイムは XrGoogleCloudAuthErrorResultANDROID :: error を XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID に設定して、このエラーを示す必要があります。

API キーの形式が検証され、ランタイムによって保存されると、非同期オペレーションは XR_SUCCESS で完了します。

有効な使用方法（暗黙的）

XrGoogleCloudAuthInfoTokenANDROID 構造体は次のように定義されます。

typedef struct XrGoogleCloudAuthInfoTokenANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        authToken;
} XrGoogleCloudAuthInfoTokenANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • authToken は、認証トークンを表す文字列へのポインタです。

この構造体が xrSetGoogleCloudAuthAsyncANDROID に渡される場合、authToken メンバーは、スペースや制御文字を含まない空でない ASCII 文字列でなければなりません。そうでない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。authToken は、さらに次の条件を満たしている必要があります。

  • Google Cloud プロジェクト用に生成された有効期限切れでない有効な認証情報である必要があります。
  • Google Cloud プロジェクトで、関連する Google Cloud API（依存する拡張機能で指定）を有効にする必要があります。

  • 認証情報は次のいずれかである必要があります。

    • アプリケーションで Google アカウントにログインして生成された、関連するスコープを含む OAuth2 アクセス トークン。
    • Google Cloud プロジェクトのサービス アカウントによって生成された、関連するクレームを含む署名付き JWT トークン。

各ケースの要件は、依存する拡張機能によって指定されます。それ以外の場合、xrSetGoogleCloudAuthAsyncANDROID の呼び出しは成功しますが、クラウド認証に依存する関数の呼び出しはすべて、それらの関数を定義する拡張機能のクラウド障害に関するドキュメントに記載されているとおりに動作します。関数が失敗を報告でき、アプリが XrGoogleCloudAuthErrorResultANDROID をその関数の出力パラメータにチェーンする場合、ランタイムは XrGoogleCloudAuthErrorResultANDROID :: error を XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID に設定して、このエラーを示す必要があります。

古いトークンが期限切れになる前に、アプリケーションは xrSetGoogleCloudAuthAsyncANDROID を介して新しいトークンを積極的に渡す必要があります。ランタイムは、新しいネットワーク リクエストを開始するときに、アプリから渡された最新のトークンを使用しなければなりません。

トークンの形式が検証され、ランタイムによって保存されると、非同期オペレーションは XR_SUCCESS で完了します。

有効な使用方法（暗黙的）

XrGoogleCloudAuthInfoKeylessANDROID 構造体は次のように定義されます。

typedef struct XrGoogleCloudAuthInfoKeylessANDROID {
    XrStructureType    type;
    const void*        next;
} XrGoogleCloudAuthInfoKeylessANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。

この構造体が xrSetGoogleCloudAuthAsyncANDROID に渡されると、ランタイムは認証情報を動的に生成する可能性があります（たとえば、Android では、ランタイムはアプリケーション プロセスから Google Play 開発者サービスと通信します）。キーレス認証が正しく設定されていない場合、ランタイムは XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID を同期的に返すことがあります。

非同期オペレーションは、認証情報を取得するために必要なネットワーク リクエストを実行します。このオペレーションの結果は、xrSetGoogleCloudAuthCompleteANDROID から XrFutureCompletionEXT :: futureResult で返されます。将来の結果が XR_SUCCESS の場合、Keyless Auth 認証情報は正常に適用されています。将来の結果が XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID の場合、アプリケーションは後で再試行してもよい。

有効な使用方法（暗黙的）

xrSetGoogleCloudAuthAsyncANDROID 関数は次のように定義されます。

XrResult xrSetGoogleCloudAuthAsyncANDROID(
    XrSession                                   session,
    const XrGoogleCloudAuthInfoBaseHeaderANDROID* authInfo,
    XrFutureEXT*                                future);

パラメータの説明

  • session は、認証情報を使用する XrSession です。
  • authInfo は、認証方法とパラメータを指定する構造体へのポインタです。その XrGoogleCloudAuthInfoBaseHeaderANDROID :: type フィールドは、特定の構造体を示します。
  • future は、作成されたフューチャーが返される XrFutureEXT ハンドルへのポインタです。関数が XR_SUCCESS を返さなかった場合は XR_NULL_HANDLE です。

Google Cloud の認証に使用する認証情報を設定します。このオペレーションは非同期です。xrPollFutureEXT を呼び出して、Future の準備完了状態を確認します。フューチャーが準備完了状態になったら、xrSetGoogleCloudAuthCompleteANDROID を呼び出して結果を取得します。

authInfo パラメータは、使用する認証方法を識別し、XrGoogleCloudAuthInfoBaseHeaderANDROID を拡張する（例: XrGoogleCloudAuthInfoApiKeyANDROID）XrGoogleCloudAuthInfoBaseHeaderANDROID::type メンバーを持つ構造体へのポインタでなければなりません。

各認証方法の具体的な要件、動作、エラー条件（同期と非同期の両方）については、それぞれのデータ構造のドキュメントをご覧ください。

有効な使用方法（暗黙的）

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

xrSetGoogleCloudAuthCompleteANDROID 関数は次のように定義されます。

XrResult xrSetGoogleCloudAuthCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrFutureCompletionEXT*                      completion);

パラメータの説明

  • session は、オペレーションの開始に使用される XrSession です。
  • future は完了する XrFutureEXT です。
  • completion は、ランタイムによって入力される XrFutureCompletionEXT へのポインタです。

今後の返品コード

XrFutureCompletionEXT :: futureResult 値:

成功

  • XR_SUCCESS : 認証情報が正常に適用されました。

失敗

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : キーレス認証に失敗しました。アプリは後で再試行できます。アプリケーションまたはデベロッパーは、成功のための特定の前提条件（Android の場合、デバイスに Google Play 開発者サービスの最新のインストールが必要であり、これらのサービスが適切に機能していることが必要であるなど）を確認することもできます。

有効な使用方法（暗黙的）

  • xrSetGoogleCloudAuthCompleteANDROID を呼び出す前に、XR_ANDROID_google_cloud_auth 拡張機能を有効にする必要があります。
  • session は、有効な XrSession ハンドルでなければなりません。
  • completion は、XrFutureCompletionEXT 構造体へのポインタでなければなりません。

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Google Cloud 認証エラー

XrGoogleCloudAuthErrorANDROID 列挙型は次のように定義されます。

typedef enum XrGoogleCloudAuthErrorANDROID {
    XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID = 0,
    XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID = -1,
    XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID = -2,
    XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID = -3,
    XR_GOOGLE_CLOUD_AUTH_ERROR_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGoogleCloudAuthErrorANDROID;

列挙子の値は次のとおりです。

列挙型の説明

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Google Cloud API の呼び出し時にエラーが発生しませんでした。

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Google Cloud API の呼び出し時に割り当てを超過しました。

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

ネットワーク接続の問題またはサーバーの可用性が原因で、Google Cloud API にアクセスできませんでした。

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Google Cloud API の呼び出し時に認証エラーが発生しました。

XrGoogleCloudAuthErrorResultANDROID 構造体は次のように定義されます。

typedef struct XrGoogleCloudAuthErrorResultANDROID {
    XrStructureType                  type;
    void*                            next;
    XrGoogleCloudAuthErrorANDROID    error;
} XrGoogleCloudAuthErrorResultANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • error は、Google Cloud にアクセスするオペレーションのエラーの原因を詳しく説明する XrGoogleCloudAuthErrorANDROID です。

Google Cloud 認証が原因でオペレーションが失敗した場合、この構造体はオペレーション結果構造体にチェーンされ、エラーに関する詳細情報を提供します。

有効な使用方法（暗黙的）

サンプルコード

XrSession session; // previously initialized
XrInstance instance; // previously initialized
XrFutureEXT future = XR_NULL_HANDLE;

// The function pointers are previously initialized using
// xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // previously initialized
PFN_xrSetGoogleCloudAuthAsyncANDROID xrSetGoogleCloudAuthAsyncANDROID; // previously initialized
PFN_xrSetGoogleCloudAuthCompleteANDROID xrSetGoogleCloudAuthCompleteANDROID; // previously initialized

auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    xrPollFutureEXT(instance, &pollInfo, &pollResult);
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Set Google Cloud auth via API key.
XrGoogleCloudAuthInfoApiKeyANDROID authApiKey{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID};
authApiKey.apiKey = "MYAPIKEY";
XrResult result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authApiKey), &future);

// Or, set Google Cloud auth via auth token:
XrGoogleCloudAuthInfoTokenANDROID authToken{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID};
authToken.authToken = "MYAUTHTOKEN";
result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authToken), &future);

// Or, set Google Cloud auth via keyless auth:
XrGoogleCloudAuthInfoKeylessANDROID authKeyless{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID};
result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authKeyless),
    &future);

// Check the result of the auth setup.
if (result == XR_ERROR_VALIDATION_FAILURE) {
  // The credentials were invalid.
} else if (result == XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID) {
  // Keyless auth was not properly setup.
} else if (result == XR_SUCCESS) {
  waitUntilReady(future);
  XrFutureCompletionEXT completion{XR_TYPE_FUTURE_COMPLETION_EXT};
  xrSetGoogleCloudAuthCompleteANDROID(session, future, &completion);

  if (completion.futureResult == XR_SUCCESS) {
    // Credentials were successfully applied.
  } else if (completion.futureResult == XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID) {
    // An error occurred when setting keyless auth credentials. This error may be retried.
  }
}

新しいコマンド

新しい構造体

新しい列挙型

新しい列挙型定数

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • XrResult の拡張 :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • XrStructureType を拡張する :

    • XR_TYPE_GOOGLE_CLOUD_AUTH_ERROR_RESULT_ANDROID
    • XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID
    • XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID
    • XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID

問題

  • リビジョン 1、2025-12-18（Ben King）

    • 拡張機能の初回説明。