XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

拡張機能の種類

インスタンス拡張

登録済みの内線番号

788

リビジョン

1

承認ステータス

未批准

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

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 設定の問題をデバッグできます。アプリケーションに Debug Messenger があり、アプリケーションに代わって Google Cloud にリクエストを送信するときに、ランタイムで対応可能なエラーが発生した場合、ランタイムはエラー メッセージとともにメッセンジャーのコールバックを呼び出します。この場合、デベロッパーはエラー メッセージと利用可能なすべてのドキュメントを参照し、アプリケーションと Google Cloud プロジェクトが Google Cloud APIs を使用するように適切に設定されていることを確認する必要があります。ランタイムは、メッセージ タイプ 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 で完了します。

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

  • XrGoogleCloudAuthInfoApiKeyANDROID を使用する前に、XR_ANDROID_google_cloud_auth 拡張機能を有効にする必要があります。
  • type は XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • apiKey は、null で終わる UTF-8 文字列でなければなりません。

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 アクセス トークン。
    • 関連するクレームを含む署名付き JWT トークン。Google Cloud プロジェクトのサービス アカウントによって生成されます。

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

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

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

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

  • XrGoogleCloudAuthInfoTokenANDROID を使用する前に、XR_ANDROID_google_cloud_auth 拡張機能を有効にする必要があります。
  • type は XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • authToken は、null で終わる UTF-8 文字列でなければなりません

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 の場合、鍵なし認証の認証情報は正常に適用されています。Future の結果が XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID の場合、アプリケーションは後でもう一度試すことができます。

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

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

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

パラメータの説明

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

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

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

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

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

戻りコード

成功

  • 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 開発者サービスがインストールされている必要があり、これらのサービスが適切に機能している必要があります）。

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

戻りコード

成功

  • 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 Auth エラー

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）

    • 拡張機能の初期説明。