XR_ANDROID_google_cloud_auth

מחרוזת שם

XR_ANDROID_google_cloud_auth

סוג התוסף

תוסף למכונה

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

788

גרסה

1

סטטוס האישור

לא אושר

תלויות של תוספים וגרסאות

XR_EXT_future

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

2025-12-18

סטטוס IP

אין תלונות ידועות על הפרת קניין רוחני.

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

ג'ון אולמן, Google
בן קינג, Google
ניהב ג'יין, Google
ג'ארד פינדר, Google

סקירה כללית

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

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

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

המבנה של 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 יאומת לצורך עיצוב ויישמר על ידי זמן הריצה.

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

  • ‫ צריך להפעיל את התוסף 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 צריך להפעיל את ממשקי ה-API הרלוונטיים של 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 , פרטי הכניסה של 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_NULL_HANDLE אם הפונקציה לא החזירה את XR_SUCCESS .

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

הפרמטר authInfo חייב להיות מצביע למבנה שבו האיבר XrGoogleCloudAuthInfoBaseHeaderANDROID :: type מזהה את שיטת האימות שבה צריך להשתמש, ומרחיב את 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 : האימות ללא מפתח נכשל. האפליקציה יכולה לנסות שוב מאוחר יותר. האפליקציה או המפתח עשויים גם לבדוק תנאים מוקדמים מסוימים להצלחה (למשל, ב-Android, במכשיר חייבת להיות התקנה עדכנית של Google Play Services והשירותים האלה חייבים לפעול כראוי).

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

קודי החזרה

הצלחה

  • 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

שגיאות אימות ב-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;

הערכים של ה-enumerants הם:

תיאור הטיפוס בן המנייה (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

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

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, יכול להיות שה-struct הזה יקושר ל-struct של תוצאת הפעולה כדי לספק מידע נוסף על השגיאה.

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

קוד לדוגמה

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

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי 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

בעיות

  • גרסה 1, 18 בדצמבר 2025 (בן קינג)

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