XR_ANDROID_google_cloud_auth

Строка имени

XR_ANDROID_google_cloud_auth

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

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

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

788

Пересмотр

1

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

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

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

XR_EXT_future

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

2025-12-18

Статус IP

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

Авторы

Джон Уллман, Google
Бен Кинг, Google
Нихав Джайн, Google
Джаред Финдер, Google

Обзор

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

В процессе разработки приложение может отлаживать проблемы с настройкой Google Cloud, используя расширение XR_EXT_debug_utils . Если в приложении есть отладочный мессенджер, и при отправке запроса в Google Cloud от имени приложения в среде выполнения возникает потенциально серьезная ошибка, среда выполнения вызывает функцию обратного вызова мессенджера с сообщением об ошибке. В этом случае разработчику следует ознакомиться с сообщением об ошибке и всей доступной документацией, а затем убедиться, что приложение и проект Google Cloud правильно настроены для использования API Google Cloud. Среда выполнения должна использовать тип сообщения XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT , уровень серьезности XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT и идентификатор сообщения «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 должны быть включены соответствующие API Google Cloud (указанные зависимыми расширениями).
  • Если ключ 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 должны быть включены соответствующие API Google Cloud (указанные зависимыми расширениями).

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

    • Токен доступа 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 Services из процесса приложения). Если аутентификация без ключей настроена неправильно, среда выполнения может синхронно вернуть XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID .

Асинхронная операция выполнит необходимые сетевые запросы для получения учетных данных. Результат этой операции будет возвращен в объекте XrFutureCompletionEXT :: futureResult из функции xrSetGoogleCloudAuthCompleteANDROID . Если результат Future равен 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 — это указатель на дескриптор объекта XrFutureEXT , в котором возвращается созданный объект `future`, или `XR_NULL_HANDLE`, если функция не вернула XR_SUCCESS .

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

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

  • Расширение 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

При вызове API Google Cloud ошибок не возникло.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

При вызове API Google Cloud превышен лимит квоты.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Не удалось подключиться к API Google Cloud, возможно, из-за проблем с сетевым подключением или недоступности сервера.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

При вызове API Google Cloud произошла ошибка аутентификации.

Структура 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.12.2025 (Бен Кинг)

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