XR_ANDROID_google_cloud_auth

String de nome

XR_ANDROID_google_cloud_auth

Tipo de extensão

Extensão de instância

Número de ramal registrado

788

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_future

Data da última modificação

2025-12-18

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

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

Visão geral

Essa extensão permite o uso de extensões baseadas no Google Cloud, permitindo que o aplicativo forneça credenciais de autenticação para as APIs do Google Cloud. O desenvolvedor precisa usar o console do Google Cloud ( https://console.cloud.google.com/) para criar um projeto na nuvem do Google Cloud para o aplicativo. Esta extensão requer a extensão XR_EXT_future .

Durante o desenvolvimento, o aplicativo pode depurar problemas com a configuração do Google Cloud usando a extensão XR_EXT_debug_utils . Se o aplicativo tiver um Debug Messenger e ocorrer um erro potencialmente acionável no ambiente de execução ao enviar uma solicitação ao Google Cloud em nome do aplicativo, o ambiente de execução vai invocar o callback do mensageiro com uma mensagem de erro. Nesse caso, o desenvolvedor precisa consultar a mensagem de erro e toda a documentação disponível e, em seguida, garantir que o aplicativo e o projeto do Google Cloud estejam configurados corretamente para usar as APIs do Google Cloud. O ambiente de execução precisa usar o tipo de mensagem XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, a gravidade XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT e o messageId "GoogleCloudError".

Autenticação

A estrutura XrGoogleCloudAuthInfoBaseHeaderANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

Essa estrutura não é usada diretamente na API, mas é estendida por outras estruturas que podem ser usadas com xrSetGoogleCloudAuthAsyncANDROID para fornecer credenciais de autenticação.

Uso válido (implícito)

A estrutura XrGoogleCloudAuthInfoApiKeyANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • apiKey é um ponteiro para uma string que representa a chave de API.

Quando essa estrutura é transmitida para xrSetGoogleCloudAuthAsyncANDROID , o membro apiKey precisa ser uma string ASCII não vazia sem espaços ou caracteres de controle. Caso contrário, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE.

apiKey precisa atender às seguintes condições:

  • Ela precisa ser uma chave de API válida gerada para seu projeto na nuvem do Google Cloud.
  • Seu projeto do Google Cloud precisa ativar as APIs relevantes do Google Cloud (especificadas pelas extensões dependentes).
  • Se a chave de API tiver restrições, elas precisam permitir as APIs do Cloud relevantes do Google Cloud e seu aplicativo.

Caso contrário, a chamada para xrSetGoogleCloudAuthAsyncANDROID será bem-sucedida, mas todas as chamadas para funções que dependem da autorização na nuvem vão agir conforme documentado para falhas na nuvem na extensão que define essas funções. Se uma função puder informar uma falha e o aplicativo encadear XrGoogleCloudAuthErrorResultANDROID ao parâmetro de saída dessa função, o ambiente de execução precisará definir XrGoogleCloudAuthErrorResultANDROID :: error como XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID para indicar esse erro.

A operação assíncrona será concluída com XR_SUCCESS assim que a chave de API for validada para formatação e armazenada pelo ambiente de execução.

Uso válido (implícito)

A estrutura XrGoogleCloudAuthInfoTokenANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • authToken é um ponteiro para uma string que representa o token de autenticação.

Quando essa estrutura é transmitida para xrSetGoogleCloudAuthAsyncANDROID , o membro authToken precisa ser uma string ASCII não vazia sem espaços ou caracteres de controle. Caso contrário, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE. authToken precisa atender às seguintes condições:

  • Ela precisa ser uma credencial válida e não expirada gerada para seu projeto na nuvem do Google Cloud.
  • Seu projeto do Google Cloud precisa ativar as APIs relevantes do Google Cloud (especificadas pelas extensões dependentes).

  • A credencial precisa ser uma das seguintes:

    • Um token de acesso OAuth2 com os escopos relevantes, gerado ao fazer login em uma Conta do Google com seu aplicativo, OU
    • Um token JWT assinado com as declarações relevantes, gerado por uma conta de serviço do seu projeto na nuvem do Google Cloud.

Os requisitos em cada caso são especificados pelas extensões dependentes. Caso contrário, a chamada para xrSetGoogleCloudAuthAsyncANDROID será bem-sucedida, mas todas as chamadas para funções que dependem da autorização do Cloud vão agir conforme documentado para falhas do Cloud na extensão que define essas funções. Se uma função puder informar uma falha e o aplicativo encadear XrGoogleCloudAuthErrorResultANDROID ao parâmetro de saída dessa função, o ambiente de execução precisará definir XrGoogleCloudAuthErrorResultANDROID :: error como XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID para indicar esse erro.

O aplicativo precisa transmitir proativamente um novo token usando xrSetGoogleCloudAuthAsyncANDROID antes que o token antigo expire. O ambiente de execução precisa usar o token mais recente transmitido pelo aplicativo ao iniciar uma nova solicitação de rede.

A operação assíncrona será concluída com XR_SUCCESS quando o token for validado para formatação e armazenado pelo ambiente de execução.

Uso válido (implícito)

A estrutura XrGoogleCloudAuthInfoKeylessANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

Quando essa estrutura é transmitida para xrSetGoogleCloudAuthAsyncANDROID, o ambiente de execução pode gerar credenciais dinamicamente (por exemplo, no Android, o ambiente de execução se comunica com o Google Play Services pelo processo do aplicativo). Se a autenticação sem chave não estiver configurada corretamente, o ambiente de execução poderá retornar XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID de forma síncrona.

A operação assíncrona vai realizar as solicitações de rede necessárias para buscar as credenciais. O resultado dessa operação será retornado em XrFutureCompletionEXT :: futureResult de xrSetGoogleCloudAuthCompleteANDROID . Se o resultado futuro for XR_SUCCESS , as credenciais de autenticação sem chave foram aplicadas. Se o resultado futuro for XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , o aplicativo poderá tentar novamente mais tarde.

Uso válido (implícito)

A função xrSetGoogleCloudAuthAsyncANDROID é definida como:

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

Descrições dos parâmetros

  • session é a XrSession que vai usar as credenciais.
  • authInfo é um ponteiro para um struct que especifica o método e os parâmetros de autenticação, com o campo XrGoogleCloudAuthInfoBaseHeaderANDROID :: type indicando o struct específico.
  • future é um ponteiro para um identificador XrFutureEXT em que o futuro criado é retornado ou XR_NULL_HANDLE se a função não retornar XR_SUCCESS .

Defina as credenciais usadas para autenticação no Google Cloud. Essa operação é assíncrona. Chame xrPollFutureEXT para verificar o estado de prontidão no futuro. Quando o futuro estiver no estado pronto, chame xrSetGoogleCloudAuthCompleteANDROID para recuperar o resultado.

O parâmetro authInfo precisa ser um ponteiro para uma estrutura em que o membro XrGoogleCloudAuthInfoBaseHeaderANDROID :: type identifica o método de autenticação a ser usado e que estende XrGoogleCloudAuthInfoBaseHeaderANDROID (por exemplo, XrGoogleCloudAuthInfoApiKeyANDROID).

Os requisitos, comportamentos e condições de erro específicos (síncronos e assíncronos) de cada método de autenticação são descritos na documentação das respectivas estruturas de dados.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A função xrSetGoogleCloudAuthCompleteANDROID é definida como:

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

Descrições dos parâmetros

  • session é a XrSession usada para iniciar a operação.
  • future é o XrFutureEXT a ser concluído.
  • completion é um ponteiro para um XrFutureCompletionEXT preenchido pelo ambiente de execução.

Códigos de retorno futuros

Valores de XrFutureCompletionEXT :: futureResult:

Sucesso

  • XR_SUCCESS : as credenciais foram aplicadas.

Falha

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : falha na autenticação sem chave. O aplicativo pode tentar novamente mais tarde. O aplicativo ou desenvolvedor pode também verificar certas condições prévias para o sucesso (por exemplo, no Android, o dispositivo precisa ter uma instalação atualizada do Google Play Services, e esses serviços precisam estar funcionando corretamente).

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

Erros de autenticação do Google Cloud

A enumeração XrGoogleCloudAuthErrorANDROID é definida como:

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;

Os enumeradores têm os seguintes valores:

Descrição do tipo enumerado

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Nenhum erro ocorreu ao invocar uma API do Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Cota excedida ao invocar uma API do Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Falha ao acessar uma API do Google Cloud, possivelmente devido a problemas de conectividade de rede ou disponibilidade do servidor.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Ocorreu um erro de autenticação ao invocar uma API do Google Cloud.

A estrutura XrGoogleCloudAuthErrorResultANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • error é o XrGoogleCloudAuthErrorANDROID que detalha a causa do erro de uma operação que acessa o Google Cloud.

Se uma operação falhar devido à autenticação do Google Cloud, essa estrutura poderá ser encadeada à estrutura de resultado operacional para fornecer mais informações sobre o erro.

Uso válido (implícito)

Exemplo de código

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

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Estendendo XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Estendendo 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

Problemas

  • Revisão 1, 18/12/2025 (Ben King)

    • Descrição inicial da extensão.