XR_ANDROID_google_cloud_auth

מחרוזת שם

XR_ANDROID_google_cloud_auth

סוג התוסף

הרחבת המכונה

מספר שלוחה רשום

788

Revision

1

סטטוס האישור

לא אושר

תלות בתוסף ובגרסה

XR_EXT_future

תאריך השינוי האחרון

2025-12-18

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים שקשורות לכתובות IP.

שותפים ביצירת התוכן

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

סקירה כללית

התוסף הזה מאפשר להשתמש בתוספים מבוססי Google Cloud, כי הוא מאפשר לאפליקציה לספק פרטי אימות ל-Google Cloud APIs. המפתח חייב להשתמש במסוף Google Cloud‏ ( https://console.cloud.google.com/ ) כדי ליצור פרויקט Google Cloud לאפליקציה. התוסף הזה דורש את התוסף XR_EXT_future .

במהלך הפיתוח, האפליקציה יכולה לנפות באגים בבעיות בהגדרות של Google Cloud באמצעות התוסף XR_EXT_debug_utils . אם לאפליקציה יש Debug Messenger, ובזמן הריצה מתרחשת שגיאה שנדרשת פעולה כדי לפתור אותה כשנשלחת בקשה אל Google Cloud בשם האפליקציה, זמן הריצה מפעיל את הקריאה החוזרת של ה-Messenger עם הודעת שגיאה. במקרה כזה, המפתח צריך לעיין בהודעת השגיאה ובכל המסמכים הזמינים, ולוודא שהאפליקציה ופרויקט בענן של Google מוגדרים בצורה נכונה לשימוש בממשקי Google Cloud API. סביבת זמן הריצה חייבת להשתמש בסוג ההודעה 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 כדי לספק פרטי כניסה לאימות.

שימוש תקף (משתמע)

• ‫ התוסף XR_ANDROID_google_cloud_auth חייב להיות מופעל לפני השימוש ב-XrGoogleCloudAuthInfoBaseHeaderANDROID
• type חייב להיות אחד מהערכים הבאים של XrStructureType: ‏ 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
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים . מידע נוסף זמין במאמר בנושא XrGoogleCloudAuthErrorResultANDROID

המבנה של 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 צריך להפעיל את Cloud APIs הרלוונטיים של Google Cloud (שמצוינים על ידי התוספים שתלויים בהם).
• אם מפתח ה-API כולל הגבלות, ההגבלות צריכות לאפשר גישה לממשקי Google Cloud API הרלוונטיים ולאפליקציה שלכם.

אחרת, הקריאה ל-xrSetGoogleCloudAuthAsyncANDROID תצליח, אבל כל הקריאות לפונקציות שתלויות בהרשאה בענן יפעלו כמו שמתואר בכשלים בענן בתוסף שמגדיר את הפונקציות האלה. אם פונקציה יכולה לדווח על כשל והאפליקציה משרשרת את XrGoogleCloudAuthErrorResultANDROID לפרמטר הפלט של הפונקציה הזו, סביבת זמן הריצה חייבת להגדיר את XrGoogleCloudAuthErrorResultANDROID :: error ל-XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID כדי לציין את השגיאה הזו.

הפעולה האסינכרונית תושלם עם XR_SUCCESS אחרי שמפתח ה-API יאומת לגבי העיצוב שלו ויישמר על ידי זמן הריצה.

שימוש תקף (משתמע)

• ‫ התוסף XR_ANDROID_google_cloud_auth חייב להיות מופעל לפני השימוש ב-XrGoogleCloudAuthInfoApiKeyANDROID
• ‫ type חייב להיות XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
• ‫ apiKey חייב להיות מחרוזת UTF-8 שמסתיימת בערך null

המבנה של 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 צריך להפעיל את Cloud APIs הרלוונטיים של Google Cloud (שמצוינים על ידי התוספים שתלויים בהם).

• האישורים חייבים להיות אחד מהסוגים הבאים:

  • אסימון גישה מסוג OAuth2 עם ההיקפים הרלוונטיים, שנוצר על ידי כניסה לחשבון Google באמצעות האפליקציה שלכם, או
  • אסימון JWT חתום עם ההצהרות הרלוונטיות, שנוצר על ידי חשבון שירות מהפרויקט שלכם ב-Google Cloud.

הדרישות בכל מקרה נקבעות על ידי התוספים התלויים. אחרת, הקריאה ל-xrSetGoogleCloudAuthAsyncANDROID תצליח, אבל כל הקריאות לפונקציות שתלויות בהרשאה בענן יפעלו כמו שמתואר בכשלים בענן בתוסף שמגדיר את הפונקציות האלה. אם פונקציה יכולה לדווח על כשל והאפליקציה משרשרת את XrGoogleCloudAuthErrorResultANDROID לפרמטר הפלט של הפונקציה הזו, סביבת זמן הריצה חייבת להגדיר את XrGoogleCloudAuthErrorResultANDROID :: error ל-XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID כדי לציין את השגיאה הזו.

האפליקציה חייבת להעביר באופן יזום אסימון חדש באמצעות xrSetGoogleCloudAuthAsyncANDROID לפני שיפוג התוקף של האסימון הישן. סביבת זמן הריצה חייבת להשתמש באסימון האחרון שהועבר על ידי האפליקציה כשמתחילים בקשה חדשה לרשת.

הפעולה האסינכרונית תושלם עם XR_SUCCESS אחרי שהאסימון יעבור אימות לגבי העיצוב שלו וזמן הריצה ישמור אותו.

שימוש תקף (משתמע)

• ‫ התוסף XR_ANDROID_google_cloud_auth חייב להיות מופעל לפני השימוש ב-XrGoogleCloudAuthInfoTokenANDROID
• ‫ type חייב להיות XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
• ‫ authToken חייב להיות מחרוזת UTF-8 שמסתיימת בערך null

המבנה 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 . אם התוצאה העתידית היא XR_SUCCESS , סימן שהוחלו בהצלחה פרטי כניסה לאימות ללא מפתח. אם התוצאה העתידית היא XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , יכול להיות שהאפליקציה תנסה שוב מאוחר יותר.

שימוש תקף (משתמע)

• ‫ חובה להפעיל את התוסף XR_ANDROID_google_cloud_auth לפני שמשתמשים ב-XrGoogleCloudAuthInfoKeylessANDROID
• ‫ type חייב להיות XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

הפונקציה xrSetGoogleCloudAuthAsyncANDROID מוגדרת כך:

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

תיאורים של פרמטרים

• ‫session הוא XrSession שישתמש בפרטי הכניסה.
• ‫authInfo הוא מצביע למבנה שמציין את שיטת האימות והפרמטרים, והשדה XrGoogleCloudAuthInfoBaseHeaderANDROID :: type שלו מציין את המבנה הספציפי.
• ‫future הוא מצביע לטיפול ב-XrFutureEXT שבו מוחזר העתיד שנוצר, או XR_NULL_HANDLE אם הפונקציה לא החזירה XR_SUCCESS .

הגדרת פרטי הכניסה שמשמשים לאימות מול Google Cloud. הפעולה הזו היא אסינכרונית. מתקשרים אל xrPollFutureEXT כדי לבדוק את מצב המוכנות בעתיד. אחרי שהעתיד יהיה במצב מוכן, צריך להפעיל את השיטה xrSetGoogleCloudAuthCompleteANDROID כדי לאחזר את התוצאה.

הפרמטר authInfo חייב להיות מצביע למבנה שחבר XrGoogleCloudAuthInfoBaseHeaderANDROID :: type שלו מזהה את שיטת האימות שבה יש להשתמש, ושהוא הרחבה של XrGoogleCloudAuthInfoBaseHeaderANDROID (למשל XrGoogleCloudAuthInfoApiKeyANDROID ).

הדרישות הספציפיות, ההתנהגויות ותנאי השגיאה (סינכרוניים ואסינכרוניים) של כל שיטת אימות מתוארים במסמכי התיעוד של מבני הנתונים המתאימים.

שימוש תקף (משתמע)

• ‫ חובה להפעיל את התוסף XR_ANDROID_google_cloud_auth לפני הקריאה ל-xrSetGoogleCloudAuthAsyncANDROID
• ‫ session חייב להיות מאחז XrSession תקין
• ‫ authInfo must להיות מצביע למבנה תקין שמבוסס על XrGoogleCloudAuthInfoBaseHeaderANDROID. ראו גם: XrGoogleCloudAuthInfoApiKeyANDROID , XrGoogleCloudAuthInfoKeylessANDROID , XrGoogleCloudAuthInfoTokenANDROID
• ‫ future חייב להיות מצביע לערך XrFutureEXT

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• 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 values:

הצלחה

• ‫XR_SUCCESS : פרטי הכניסה הוחלו בהצלחה.

Failure

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

Failure

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

הערכים האפשריים הם:

תיאור ה-Enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

לא אירעה שגיאה בהפעלת Google Cloud API.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

הייתה חריגה מהמכסה בהפעלת Google Cloud API.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

הגישה לממשק API של Google Cloud נכשלה, יכול להיות בגלל בעיות בקישוריות לרשת או בזמינות השרת.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

אירעה שגיאת אימות במהלך הפעלת Google Cloud API.

המבנה XrGoogleCloudAuthErrorResultANDROID מוגדר כך:

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

תיאורי חברים

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫error הוא XrGoogleCloudAuthErrorANDROID שמפרט את הסיבה לשגיאה בפעולה שמתבצעת בגישה ל-Google Cloud.

אם פעולה נכשלת בגלל אימות ב-Google Cloud, יכול להיות שהמבנה הזה יצורף למבנה של תוצאת הפעולה כדי לספק מידע נוסף על השגיאה.

שימוש תקף (משתמע)

• ‫ התוסף XR_ANDROID_google_cloud_auth חייב להיות מופעל לפני השימוש ב-XrGoogleCloudAuthErrorResultANDROID
• ‫ type חייב להיות XR_TYPE_GOOGLE_CLOUD_AUTH_ERROR_RESULT_ANDROID
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
• ‫ error חייב להיות ערך תקין של XrGoogleCloudAuthErrorANDROID

קוד לדוגמה

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

פקודות חדשות

• xrSetGoogleCloudAuthAsyncANDROID
• xrSetGoogleCloudAuthCompleteANDROID

מבנים חדשים

• XrGoogleCloudAuthInfoApiKeyANDROID
• XrGoogleCloudAuthInfoBaseHeaderANDROID
• XrGoogleCloudAuthInfoKeylessANDROID
• XrGoogleCloudAuthInfoTokenANDROID

• הרחבה של XrGoogleCloudAuthInfoBaseHeaderANDROID :

  • XrGoogleCloudAuthErrorResultANDROID

New Enums

• XrGoogleCloudAuthErrorANDROID

New Enum Constants

• 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, ‏2025-12-18 (בן קינג)

  • התיאור הראשוני של התוסף.