XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

788

Revision

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

XR_EXT_future

Дата последнего изменения

2025-12-18

Статус IP-адреса

Нет известных претензий в отношении интеллектуальной собственности.

Авторы

Джон Ульман (John Ullman), Google
Бен Кинг (Ben King), Google
Нихав Джайн (Nihav Jain), Google
Джаред Финдер (Jared Finder), Google

Обзор

Это расширение позволяет использовать облачные расширения Google Cloud, предоставляя приложению учетные данные для аутентификации в Google Cloud API. Разработчик должен использовать Google Cloud Console ( https://console.cloud.google.com/), чтобы создать проект Google Cloud для приложения. Для работы этого расширения требуется расширение XR_EXT_future .

Во время разработки приложение может отлаживать проблемы с настройкой Google Cloud с помощью расширения XR_EXT_debug_utils . Если в приложении есть Debug Messenger и в среде выполнения возникает ошибка, требующая действий, при отправке запроса в Google Cloud от имени приложения среда выполнения вызывает обратный вызов мессенджера с сообщением об ошибке. В этом случае разработчику следует ознакомиться с сообщением об ошибке и всей доступной документацией, а затем убедиться, что приложение и облачный проект 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 для предоставления учетных данных.

Допустимое использование (неявное)

Структура 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 должны соответствовать следующим условиям:

  • Это должен быть действительный ключ API, сгенерированный для вашего облачного проекта Google Cloud.
  • В вашем облачном проекте Google Cloud должны быть включены нужные Cloud API (указанные в зависимых расширениях).
  • Если для ключа API заданы ограничения, они должны разрешать доступ к соответствующим API Google Cloud и вашему приложению.

В противном случае вызов xrSetGoogleCloudAuthAsyncANDROID будет успешным, но все вызовы функций, зависящих от облачной авторизации, будут действовать так, как описано в документации для сбоев облака в расширении, определяющем эти функции. Если функция может сообщить о сбое и приложение связывает XrGoogleCloudAuthErrorResultANDROID с выходным параметром этой функции, среда выполнения должна задать для XrGoogleCloudAuthErrorResultANDROID :: error значение XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID, чтобы указать на эту ошибку.

Асинхронная операция завершится с XR_SUCCESS, как только ключ API будет проверен на соответствие формату и сохранен средой выполнения.

Допустимое использование (неявное)

Структура 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 должны быть включены нужные Cloud API (указанные в зависимых расширениях).

  • Учетные данные должны быть одними из следующих:

    • токен доступа OAuth2 с соответствующими областями действия, сгенерированный при входе в аккаунт Google через ваше приложение;
    • Подписанный токен JWT с соответствующими утверждениями, сгенерированный сервисным аккаунтом из вашего облачного проекта Google Cloud.

Требования в каждом случае определяются зависимыми расширениями. В противном случае вызов 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.

Асинхронная операция выполнит необходимые сетевые запросы для получения учетных данных. Результат этой операции будет возвращен в XrFutureCompletionEXT :: futureResult из xrSetGoogleCloudAuthCompleteANDROID . Если в будущем вы получите результат XR_SUCCESS , значит учетные данные для аутентификации без ключа были успешно применены. Если возвращается результат XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , приложение может повторить попытку позже.

Допустимое использование (неявное)

Функция xrSetGoogleCloudAuthAsyncANDROID определяется следующим образом:

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

Описание параметров

  • session – это XrSession, который будет использовать учетные данные.
  • authInfo – указатель на структуру, определяющую способ аутентификации и параметры, а поле XrGoogleCloudAuthInfoBaseHeaderANDROID :: type указывает на конкретную структуру.
  • future – указатель на дескриптор XrFutureEXT, в котором возвращается созданный объект Future, или XR_NULL_HANDLE, если функция не вернула XR_SUCCESS .

Укажите учетные данные для аутентификации в Google Cloud. Эта операция является асинхронной. Вызовите xrPollFutureEXT, чтобы проверить состояние готовности. Когда объект 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_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

Перечисление 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, эта структура может быть связана со структурой результата операции, чтобы предоставить больше информации об ошибке.

Допустимое использование (неявное)

Пример кода

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, 18 декабря 2025 г. (Бен Кинг)

    • Начальное описание расширения.