XR_ANDROID_google_cloud_auth

رشته نام

XR_ANDROID_google_cloud_auth

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۸۸ عدد

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_EXT_future

آخرین تاریخ اصلاح

۲۰۲۵-۱۲-۱۸

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

جان اولمن، گوگل
بن کینگ، گوگل
نیهاو جین، گوگل
جارد فایندر، گوگل

نمای کلی

این افزونه با اجازه دادن به برنامه برای ارائه اعتبارنامه‌های احراز هویت برای APIهای Google Cloud، امکان استفاده از افزونه‌های مبتنی بر Google Cloud را فراهم می‌کند. توسعه‌دهنده باید از کنسول Google Cloud ( https://console.cloud.google.com/ ) برای ایجاد یک پروژه Google Cloud برای برنامه استفاده کند. این افزونه به افزونه XR_EXT_future نیاز دارد.

در طول توسعه، برنامه می‌تواند با استفاده از افزونه XR_EXT_debug_utils مشکلات مربوط به تنظیمات Google Cloud خود را اشکال‌زدایی کند. اگر برنامه دارای یک پیام‌رسان اشکال‌زدایی باشد و هنگام ارسال درخواست به Google Cloud از طرف برنامه، خطایی که احتمالاً قابل پیگیری است در زمان اجرا رخ دهد، زمان اجرا، فراخوانی پیام‌رسان را با یک پیام خطا فراخوانی می‌کند. در این حالت، توسعه‌دهنده باید پیام خطا و تمام مستندات موجود را بررسی کند و سپس اطمینان حاصل کند که برنامه و پروژه Google Cloud به درستی برای استفاده از APIهای Google Cloud تنظیم شده‌اند. زمان اجرا باید از نوع پیام 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 شما باید 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 یک اشاره‌گر به رشته‌ای است که نشان‌دهنده‌ی توکن auth است.

وقتی این ساختار به xrSetGoogleCloudAuthAsyncANDROID ارسال می‌شود، عضو authToken باید یک رشته ASCII غیرخالی بدون فاصله یا کاراکترهای کنترلی باشد، در غیر این صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند. authToken باید شرایط زیر را نیز برآورده کند:

  • این باید یک اعتبارنامه معتبر و منقضی نشده باشد که برای پروژه Google Cloud شما ایجاد شده است.
  • پروژه Google Cloud شما باید APIهای Google Cloud مربوطه (که توسط افزونه‌های مربوطه مشخص شده‌اند) را فعال کند.

  • اعتبارنامه باید یکی از موارد زیر باشد:

    • یک توکن دسترسی OAuth2 با محدوده‌های مربوطه، که با ورود به حساب گوگل با برنامه شما ایجاد می‌شود، یا
    • یک توکن 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 ارسال می‌شود، ممکن است زمان اجرا به صورت پویا اعتبارنامه‌ها را تولید کند (مثلاً در اندروید، زمان اجرا از طریق فرآیند برنامه با سرویس‌های Google Play ارتباط برقرار می‌کند). اگر Keyless Auth به درستی تنظیم نشده باشد، زمان اجرا ممکن است XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID به صورت همزمان برگرداند.

عملیات ناهمزمان، درخواست‌های شبکه لازم برای دریافت اعتبارنامه‌ها را انجام می‌دهد. نتیجه این عملیات در XrFutureCompletionEXT :: futureResult from xrSetGoogleCloudAuthCompleteANDROID بازگردانده می‌شود. اگر نتیجه بعدی XR_SUCCESS باشد، اعتبارنامه‌های Keyless Auth با موفقیت اعمال شده‌اند. اگر نتیجه بعدی 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_SUCCESS برنگرداند، XR_NULL_HANDLE است .

اعتبارنامه‌های مورد استفاده برای احراز هویت با Google Cloud را تنظیم کنید. این عملیات ناهمزمان است. برای بررسی وضعیت آماده بودن آینده، xrPollFutureEXT را فراخوانی کنید. پس از اینکه آینده در وضعیت آماده قرار گرفت، xrSetGoogleCloudAuthCompleteANDROID را برای بازیابی نتیجه فراخوانی کنید.

پارامتر authInfo باید اشاره‌گری به یک struct باشد که عضو type آن یعنی XrGoogleCloudAuthInfoBaseHeaderANDROID :: روش احراز هویت مورد استفاده را مشخص می‌کند و از 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 : احراز هویت بدون کلید ناموفق بود. برنامه می‌تواند بعداً دوباره امتحان کند. برنامه یا توسعه‌دهنده همچنین ممکن است پیش‌شرط‌های خاصی را برای موفقیت بررسی کند (مثلاً در اندروید، دستگاه باید نصب به‌روزی از سرویس‌های گوگل پلی داشته باشد و این سرویس‌ها باید به درستی کار کنند).

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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

خطاهای تأیید اعتبار گوگل کلود

شمارش 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 گوگل کلود، هیچ خطایی رخ نداد.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

هنگام فراخوانی یک API گوگل کلود، از سهمیه تعیین‌شده تجاوز شد.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

احتمالاً به دلیل مشکلات اتصال شبکه یا در دسترس نبودن سرور، دسترسی به API گوگل کلود ناموفق بود.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

هنگام فراخوانی API گوگل کلود، خطایی در احراز هویت رخ داد.

ساختار XrGoogleCloudAuthErrorResultANDROID به صورت زیر تعریف شده است: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • error ، خطای XrGoogleCloudAuthErrorANDROID است که علت خطای مربوط به دسترسی به 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.
  }
}

دستورات جدید

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • 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

مسائل

  • نسخه ۱، ۲۰۲۵-۱۲-۱۸ (بن کینگ)

    • توضیحات اولیه افزونه