Android XR for OpenXR | Android Developers

Android 开发者峰会回归，并专门设置了 Android XR 专题。欢迎观看、试用并向我们发送反馈！

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

XR_ANDROID_google_cloud_auth

名称字符串

XR_ANDROID_google_cloud_auth

扩展程序类型

实例扩展程序

已注册的扩展程序编号

788

修订版本

批准状态

未批准

扩展程序和版本依赖项

XR_EXT_future

上次修改日期

2025-12-18

IP 状态

没有已知的 IP 权利主张。

创作贡献者

John Ullman，Google
Ben King，Google
Nihav Jain，Google
Jared Finder，Google

概览

此扩展程序允许应用为 Google Cloud API 提供身份验证凭据，从而支持使用基于 Google Cloud 的扩展程序。开发者必须使用 Google Cloud 控制台 ( https://console.cloud.google.com/) 为应用创建 Google Cloud 项目。此扩展程序需要扩展程序 XR_EXT_future。

在开发过程中，应用可以使用扩展程序 XR_EXT_debug_utils 调试其 Google Cloud 设置中的问题。如果应用具有调试 Messenger，并且在代表应用向 Google Cloud 发送请求时，运行时中发生可能可采取措施的错误，则运行时会调用 Messenger 的回调并显示出错提示。在这种情况下，开发者应查阅出错提示和所有可用文档，然后确保应用和 Google Cloud 云项目已正确设置，以便使用 Google Cloud API。运行时必须使用消息类型 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 搭配使用，以提供身份验证凭证。

有效用法（隐式）

必须先启用 XR_ANDROID_google_cloud_auth 扩展程序，然后才能使用 XrGoogleCloudAuthInfoBaseHeaderANDROID
type 必须是以下 XrStructureType 值之一：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
next 必须是 NULL 或指向结构链中下一个结构的有效指针。另请参阅：XrGoogleCloudAuthErrorResultANDROID

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。

有效用法（隐式）

必须先启用 XR_ANDROID_google_cloud_auth 扩展程序，然后才能使用 XrGoogleCloudAuthInfoApiKeyANDROID
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 访问令牌，或者
- 由 Google Cloud 项目中的服务账号生成的、包含相关声明的已签名 JWT 令牌。

每种情况下的要求均由依赖扩展程序指定。否则，对 xrSetGoogleCloudAuthAsyncANDROID 的调用会成功，但对依赖于云授权的函数的所有调用都会按照定义这些函数的扩展程序中有关云故障的说明执行。如果某个函数可以报告失败，并且应用将 XrGoogleCloudAuthErrorResultANDROID 链接到该函数的输出参数，则运行时必须将 XrGoogleCloudAuthErrorResultANDROID :: error 设置为 XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID，以指示此错误。

应用必须在旧令牌到期之前，通过 xrSetGoogleCloudAuthAsyncANDROID 主动传入新令牌。在启动新的网络请求时，运行时必须使用应用传入的最新令牌。

一旦令牌通过格式验证并由运行时存储，异步操作将完成并返回 XR_SUCCESS。

有效用法（隐式）

必须先启用 XR_ANDROID_google_cloud_auth 扩展程序，然后才能使用 XrGoogleCloudAuthInfoTokenANDROID
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 中返回。如果 future 结果为 XR_SUCCESS，则表示已成功应用无密钥身份验证凭证。如果未来结果为 XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID，则应用可以稍后重试。

有效用法（隐式）

必须先启用 XR_ANDROID_google_cloud_auth 扩展程序，然后才能使用 XrGoogleCloudAuthInfoKeylessANDROID
type 必须为 XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID
next 必须为 NULL 或指向结构链中下一个结构的有效指针

xrSetGoogleCloudAuthAsyncANDROID 函数的定义如下：

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

参数说明

session 是将使用这些凭据的 XrSession。
authInfo 是一个指向结构体的指针，该结构体指定了身份验证方法和参数，其 XrGoogleCloudAuthInfoBaseHeaderANDROID :: type 字段指示了具体结构体。
future 是一个指向 XrFutureEXT 句柄的指针，创建的 future 将通过该句柄返回；如果函数未返回 XR_SUCCESS，则为 XR_NULL_HANDLE。

设置用于向 Google Cloud 进行身份验证的凭据。此操作是异步的。调用 xrPollFutureEXT 以检查 future 的就绪状态。当 future 处于就绪状态后，调用 xrSetGoogleCloudAuthCompleteANDROID 即可检索结果。

authInfo 参数必须是指向某个结构体的指针，该结构体的 XrGoogleCloudAuthInfoBaseHeaderANDROID :: type 成员用于标识要使用的身份验证方法，并且该结构体扩展了 XrGoogleCloudAuthInfoBaseHeaderANDROID（例如 XrGoogleCloudAuthInfoApiKeyANDROID）。

每种身份验证方法的具体要求、行为和错误条件（同步和异步）均在其各自数据结构的文档中进行了说明。

有效用法（隐式）

必须先启用 XR_ANDROID_google_cloud_auth 扩展程序，然后才能调用 xrSetGoogleCloudAuthAsyncANDROID
session 必须是有效的 XrSession 句柄
authInfo 必须是指向基于 XrGoogleCloudAuthInfoBaseHeaderANDROID 的有效结构的指针。另请参阅：XrGoogleCloudAuthInfoApiKeyANDROID、XrGoogleCloudAuthInfoKeylessANDROID、XrGoogleCloudAuthInfoTokenANDROID
future 必须是指向 XrFutureEXT 值的指针

返回代码

成功

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_ANDROID_google_cloud_auth 扩展程序，然后才能调用 xrSetGoogleCloudAuthCompleteANDROID
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 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 是 XrGoogleCloudAuthErrorANDROID，详细说明了访问 Google Cloud 的操作出错的原因。

如果操作因 Google Cloud 身份验证而失败，此结构体可能会链接到操作结果结构体，以提供有关错误的更多信息。

有效用法（隐式）

必须先启用 XR_ANDROID_google_cloud_auth 扩展程序，然后才能使用 XrGoogleCloudAuthErrorResultANDROID
type 必须为 XR_TYPE_GOOGLE_CLOUD_AUTH_ERROR_RESULT_ANDROID
next 必须为 NULL 或指向结构链中下一个结构的有效指针
error 必须是有效的 XrGoogleCloudAuthErrorANDROID 值

示例代码

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.
  }
}

新结构

XrGoogleCloudAuthInfoApiKeyANDROID
XrGoogleCloudAuthInfoBaseHeaderANDROID
XrGoogleCloudAuthInfoKeylessANDROID
XrGoogleCloudAuthInfoTokenANDROID
扩展 XrGoogleCloudAuthInfoBaseHeaderANDROID：
- XrGoogleCloudAuthErrorResultANDROID

新枚举

XrGoogleCloudAuthErrorANDROID

新枚举常量

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）
- 初始扩展程序说明。