XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

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 bir fikri mülkiyet 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 bilgileri sağlamasına izin vererek Google Cloud tabanlı uzantıların kullanılmasını sağlar. Geliştirici, uygulama için bir 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.

Uygulama, geliştirme aşamasında XR_EXT_debug_utils uzantısını kullanarak Google Cloud kurulumuyla ilgili sorunları ayıklayabilir. Uygulamada bir hata ayıklama mesajı 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ı, mesajın geri çağırma işlevini bir hata mesajıyla çağırır. Bu durumda geliştirici, hata mesajını ve mevcut tüm belgeleri incelemeli, ardından uygulamanın ve Google Cloud projesinin Google Cloud API'lerini kullanacak şekilde doğru şekilde ayarlandığından emin olmalıdır. Çalışma zamanı, XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT mesaj türünü, XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT önem derecesini ve "GoogleCloudError" messageId değerini 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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.

Bu yapı, API'de doğrudan kullanılmaz ancak kimlik doğrulama 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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.
  • apiKey, API anahtarını temsil eden bir dizeye işaret eder.

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 değerini döndürmelidir.

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

  • Google Cloud projeniz için oluşturulmuş geçerli bir API anahtarı olmalıdır.
  • Google Cloud projeniz, ilgili Google Cloud API'lerini (bağlı uzantılar tarafından belirtilen) etkinleştirmelidir.
  • API anahtarında kısıtlamalar varsa bu 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ıdaki bulut hataları için belgelendiği şekilde davranır. Bir işlev hata bildirebiliyorsa ve uygulama, XrGoogleCloudAuthErrorResultANDROID'yi 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ının biçimlendirmesi doğrulandıktan ve anahtar ç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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.
  • authToken, kimlik doğrulama jetonunu temsil eden bir dizeye işaret eder.

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 değerini döndürmelidir. authToken ayrıca aşağıdaki koşulları da karşılamalıdır:

  • Bu, 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ğlı 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 kapsamlara sahip bir OAuth2 erişim jetonu VEYA
    • Google Cloud projenizdeki bir hizmet hesabı tarafından oluşturulan, ilgili hak taleplerini içeren imzalı bir JWT jetonu.

Her bir durumdaki şartlar, bağımlı uzantılar tarafından belirtilir. 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ıdaki bulut hataları için belgelendiği şekilde davranır. Bir işlev hata bildirebiliyorsa ve uygulama, XrGoogleCloudAuthErrorResultANDROID'yi 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.

Biçimlendirme için doğrulanan ve çalışma zamanı tarafından depolanan jeton, eşzamansız işlemi XR_SUCCESS ile tamamlar.

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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.

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

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

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 işaret eder. XrGoogleCloudAuthInfoBaseHeaderANDROID :: type alanı, belirli yapıyı gösterir.
  • future, oluşturulan geleceğin döndürüldüğü bir XrFutureEXT tutamağına işaret eder veya işlev XR_SUCCESS değerini döndürmediyse XR_NULL_HANDLE değerini döndürür.

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

authInfo parametresi, XrGoogleCloudAuthInfoBaseHeaderANDROID :: type üyesi kullanılacak kimlik doğrulama yöntemini tanımlayan ve XrGoogleCloudAuthInfoBaseHeaderANDROID'i (ör. XrGoogleCloudAuthInfoApiKeyANDROID) genişleten bir yapıya 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ıyla ilgili dokümanlarda açıklanmıştır.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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, tamamlanması gereken XrFutureEXT.
  • 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ı.

Hata

  • 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ılı bir işlem için belirli ön koşulları da kontrol edebilir (ör. Android'de cihazda Google Play Hizmetleri'nin güncel bir sürümü yüklü olmalı ve bu hizmetler düzgün çalışıyor olmalıdır).

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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ıcılar 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 ç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'ye erişilemedi.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Google Cloud API çağrılırken bir 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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.
  • 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ğrulaması 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 Enum Veri Türleri

Yeni Enum 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

  • Düzeltme 1, 18.12.2025 (Ben King)

    • İlk uzantı açıklaması.