XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

788

Düzeltme

1

Onay Durumu

Onaylanmadı

Uzantı ve Sürüm Bağımlılıkları

XR_EXT_future

Son Değiştirilme Tarihi

2025-12-18

IP Durumu

Bilinen IP hak talebi yok.

Katkıda bulunanlar

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

Genel Bakış

Bu uzantı, uygulamanın Google Cloud API'leri için kimlik doğrulama kimlik bilgileri sağlamasına izin vererek Google Cloud tabanlı uzantıların kullanılmasını sağlar. Geliştirici, uygulama için Google Cloud projesi oluşturmak üzere Google Cloud Console'u ( https://console.cloud.google.com/ ) kullanmalıdır. Bu uzantı için XR_EXT_future uzantısı gerekir .

Geliştirme sırasında uygulama, XR_EXT_debug_utils uzantısını kullanarak Google Cloud kurulumuyla ilgili sorunların hatalarını ayıklayabilir. Uygulamada bir Debug Messenger varsa ve uygulama adına Google Cloud'a istek gönderilirken çalışma zamanında işlem yapılabilir bir hata oluşursa çalışma zamanı, hata mesajıyla birlikte Messenger'ın geri çağırma işlevini çağırır. Bu durumda geliştirici, hata mesajına ve mevcut tüm belgelere başvurmalı, ardından uygulamanın ve Google Cloud projesinin Google Cloud API'lerini kullanmak için doğru şekilde ayarlandığından emin olmalıdır. Çalışma zamanı mutlaka mesaj türü XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, önem derecesi XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT ve mesaj kimliği "GoogleCloudError" değerlerini kullanmalıdır.

Kimlik doğrulama

XrGoogleCloudAuthInfoBaseHeaderANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.

Bu yapı doğrudan API'de kullanılmaz ancak kimlik doğrulama kimlik bilgileri sağlamak için xrSetGoogleCloudAuthAsyncANDROID ile kullanılabilen diğer yapılar tarafından genişletilir.

Geçerli Kullanım (Dolaylı)

XrGoogleCloudAuthInfoApiKeyANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • apiKey, API anahtarını temsil eden bir dizeye yönelik işaretçidir.

Bu yapı xrSetGoogleCloudAuthAsyncANDROID'e iletildiğinde apiKey üyesi, boşluk veya kontrol karakteri içermeyen, boş olmayan bir ASCII dizesi olmalıdır. Aksi takdirde, çalışma zamanı XR_ERROR_VALIDATION_FAILURE döndürmelidir.

apiKey Aşağıdaki koşulları da karşılamalıdır:

  • Bu anahtar, Google Cloud projeniz için oluşturulmuş geçerli bir API anahtarı olmalıdır.
  • Google Cloud projeniz, ilgili Google Cloud API'lerini (bağımlı uzantılar tarafından belirtilen) etkinleştirmelidir.
  • API anahtarında kısıtlamalar varsa kısıtlamalar, ilgili Google Cloud API'lerine ve uygulamanıza izin vermelidir.

Aksi takdirde, xrSetGoogleCloudAuthAsyncANDROID çağrısı başarılı olur ancak bulut yetkilendirmesine bağlı işlevlere yapılan tüm çağrılar, bu işlevleri tanımlayan uzantıda bulut hataları için belgelendiği şekilde davranır. Bir işlev hatayı bildirebiliyorsa ve uygulama, XrGoogleCloudAuthErrorResultANDROID'i bu işlevin çıkış parametresine zincirliyorsa çalışma zamanı, bu hatayı belirtmek için XrGoogleCloudAuthErrorResultANDROID :: error değerini XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID olarak ayarlamalıdır.

API anahtarı biçimlendirme açısından doğrulanıp çalışma zamanı tarafından depolandıktan sonra, eşzamansız işlem XR_SUCCESS ile tamamlanır.

Geçerli Kullanım (Dolaylı)

XrGoogleCloudAuthInfoTokenANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • authToken, kimlik doğrulama jetonunu temsil eden bir dizenin işaretçisidir.

Bu yapı xrSetGoogleCloudAuthAsyncANDROID'e iletildiğinde authToken üyesi, boşluk veya kontrol karakteri içermeyen, boş olmayan bir ASCII dizesi olmalıdır. Aksi takdirde, çalışma zamanı XR_ERROR_VALIDATION_FAILURE döndürmelidir. authToken aşağıdaki koşulları da karşılamalıdır:

  • Google Cloud projeniz için oluşturulmuş geçerli ve süresi dolmamış bir kimlik bilgisi olmalıdır.
  • Google Cloud projeniz, ilgili Google Cloud API'lerini (bağımlı uzantılar tarafından belirtilen) etkinleştirmelidir.

  • Kimlik bilgisi aşağıdakilerden biri olmalıdır:

    • Uygulamanızla bir Google Hesabı'nda oturum açarak oluşturulan, ilgili kapsamları içeren bir OAuth2 erişim jetonu VEYA
    • Google Cloud projenizdeki bir hizmet hesabı tarafından oluşturulan, ilgili talepleri içeren imzalı bir JWT jetonu.

Her durumda geçerli olan şartlar, bağlı uzantılar tarafından belirlenir. Aksi takdirde, xrSetGoogleCloudAuthAsyncANDROID çağrısı başarılı olur ancak bulut yetkilendirmesine bağlı işlevlere yapılan tüm çağrılar, bu işlevleri tanımlayan uzantıda bulut hataları için belgelendiği şekilde davranır. Bir işlev hatayı bildirebiliyorsa ve uygulama, XrGoogleCloudAuthErrorResultANDROID'i bu işlevin çıkış parametresine zincirliyorsa çalışma zamanı, bu hatayı belirtmek için XrGoogleCloudAuthErrorResultANDROID :: error değerini XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID olarak ayarlamalıdır.

Uygulama, eski jetonun süresi dolmadan önce xrSetGoogleCloudAuthAsyncANDROID aracılığıyla proaktif olarak yeni bir jeton iletmelidir. Çalışma zamanı, yeni bir ağ isteği başlatırken uygulama tarafından iletilen en son jetonu kullanmalıdır.

Asenkron işlem, biçimlendirme için jeton doğrulandıktan ve çalışma zamanı tarafından depolandıktan sonra XR_SUCCESS ile tamamlanır.

Geçerli Kullanım (Dolaylı)

XrGoogleCloudAuthInfoKeylessANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.

Bu yapı xrSetGoogleCloudAuthAsyncANDROID'e iletildiğinde çalışma zamanı , kimlik bilgilerini dinamik olarak oluşturabilir (ör. Android'de çalışma zamanı, uygulama sürecinden Google Play Hizmetleri ile iletişim kurar). Anahtarsız kimlik doğrulama düzgün şekilde ayarlanmamışsa çalışma zamanı eşzamanlı olarak XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID döndürebilir.

Eşzamansız işlem, kimlik bilgilerini getirmek için gerekli ağ isteklerini gerçekleştirir. Bu işlemin sonucu, XrFutureCompletionEXT :: futureResult içinde xrSetGoogleCloudAuthCompleteANDROID olarak döndürülür . Gelecekteki sonuç XR_SUCCESS ise Keyless Auth kimlik bilgileri başarıyla uygulanmıştır. Gelecekteki sonuç XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID ise uygulama daha sonra tekrar denenebilir.

Geçerli Kullanım (Dolaylı)

xrSetGoogleCloudAuthAsyncANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

  • session, kimlik bilgilerini kullanacak XrSession'dır.
  • authInfo, kimlik doğrulama yöntemini ve parametrelerini belirten bir yapıya yönelik işaretçidir. XrGoogleCloudAuthInfoBaseHeaderANDROID :: type alanı, belirli yapıyı gösterir.
  • future, oluşturulan geleceğin döndürüldüğü bir XrFutureEXT tutamacına yönelik bir işaretçidir veya işlev XR_SUCCESS değerini döndürmediyse XR_NULL_HANDLE değeridir .

Google Cloud ile kimlik doğrulaması yapmak için kullanılan kimlik bilgilerini ayarlayın. Bu işlem eşzamansızdır. Gelecekte hazır durumunu kontrol etmek için xrPollFutureEXT'yi çağırın. Gelecek hazır durumuna geldiğinde sonucu almak için xrSetGoogleCloudAuthCompleteANDROID'i çağırın.

authInfo parametresi, XrGoogleCloudAuthInfoBaseHeaderANDROID :: type üyesi kullanılacak kimlik doğrulama yöntemini tanımlayan ve XrGoogleCloudAuthInfoBaseHeaderANDROID'i genişleten bir yapıya (ör. XrGoogleCloudAuthInfoApiKeyANDROID) yönelik bir işaretçi olmalıdır.

Her kimlik doğrulama yönteminin özel gereksinimleri, davranışları ve hata koşulları (hem eşzamanlı hem de eşzamansız) ilgili veri yapıları dokümanlarında açıklanmıştır.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • 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 işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

  • session, işlemi başlatmak için kullanılan XrSession'dır.
  • future, tamamlanacak XrFutureEXT'dir.
  • completion, çalışma zamanı tarafından doldurulan bir XrFutureCompletionEXT işaretçisidir.

Gelecekteki İade Kodları

XrFutureCompletionEXT :: futureResult değerleri:

Başarılı

  • XR_SUCCESS : Kimlik bilgileri başarıyla uygulandı.

Başarısız

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Anahtarsız kimlik doğrulama başarısız oldu. Uygulama daha sonra tekrar deneyebilir. Uygulama veya geliştirici, başarı için belirli ön koşulları da kontrol edebilir (ör. Android'de cihazda Google Play Hizmetleri'nin güncel bir yüklemesi olmalı ve bu hizmetler düzgün şekilde çalışıyor olmalıdır).

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • 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 kimlik doğrulama hataları

XrGoogleCloudAuthErrorANDROID numaralandırması şu şekilde tanımlanır:

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;

Numaralandırılmış değerler aşağıdaki değerlere sahiptir:

Enum Açıklaması

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Google Cloud API çağrılırken hata oluşmadı.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Google Cloud API'si çağrılırken kota aşıldı.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Ağ bağlantısı sorunları veya sunucu kullanılabilirliği nedeniyle Google Cloud API'sine ulaşılamadı.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Bir Google Cloud API'si çağrılırken kimlik doğrulama hatası oluştu.

XrGoogleCloudAuthErrorResultANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • error, Google Cloud'a erişen bir işlemin hatasının nedenini ayrıntılı olarak açıklayan XrGoogleCloudAuthErrorANDROID'dir.

Bir işlem Google Cloud kimlik doğrulama nedeniyle başarısız olursa bu yapı, hatayla ilgili daha fazla bilgi sağlamak için işlem sonucu yapısına zincirlenebilir.

Geçerli Kullanım (Dolaylı)

Örnek kod

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

Yeni Komutlar

Yeni Yapılar

Yeni Sıralamalar

Yeni Numaralandırılmış Değer Sabitleri

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • XrResult'ı genişletme :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • XrStructureType'ı genişletme :

    • 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

Sayılar

  • 1. düzeltme, 18.12.2025 (Ben King)

    • İlk uzantı açıklaması.