XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

788

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

XR_EXT_future

تاريخ آخر تعديل

2025-12-18

حالة الملكية الفكرية

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

جون أولمان، Google
بن كينغ، Google
نيهاف جاين، Google
جاريد فايندر، Google

نظرة عامة

تتيح هذه الإضافة استخدام الإضافات المستندة إلى السحابة الإلكترونية من Google من خلال السماح للتطبيق بتقديم بيانات اعتماد المصادقة لواجهات Google Cloud API. يجب على المطوّر استخدام Google Cloud Console‏ ( https://console.cloud.google.com/‎ ) لإنشاء مشروع على Google Cloud للتطبيق. تتطلّب هذه الإضافة توفّر الإضافة XR_EXT_future .

أثناء عملية التطوير، يمكن للتطبيق تصحيح أخطاء المشاكل في إعداد Google Cloud باستخدام الإضافة XR_EXT_debug_utils . إذا كان التطبيق يتضمّن Debug Messenger، وحدث خطأ يمكن اتخاذ إجراء بشأنه في وقت التشغيل عند إرسال طلب إلى Google Cloud نيابةً عن التطبيق، يستدعي وقت التشغيل دالة الاستدعاء الخاصة ببرنامج المراسلة مع رسالة خطأ. في هذه الحالة، على المطوّر الاطّلاع على رسالة الخطأ وجميع المستندات المتاحة، ثم التأكّد من إعداد التطبيق ومشروع Google Cloud بشكل صحيح لاستخدام واجهات Google Cloud API. يجب أن تستخدم بيئة التشغيل نوع الرسالة XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT ومستوى الخطورة XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT ورقم تعريف الرسالة "GoogleCloudError".

المصادقة

يتم تحديد بنية XrGoogleCloudAuthInfoBaseHeaderANDROID على النحو التالي:

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

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.

لا يتم استخدام هذه البنية مباشرةً في واجهة برمجة التطبيقات، ولكن يتم توسيعها من خلال بنيات أخرى يمكن استخدامها مع xrSetGoogleCloudAuthAsyncANDROID لتوفير بيانات اعتماد المصادقة.

الاستخدام الصالح (ضمني)

يتم تحديد بنية XrGoogleCloudAuthInfoApiKeyANDROID على النحو التالي:

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

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫apiKey هو مؤشر إلى سلسلة تمثّل مفتاح واجهة برمجة التطبيقات.

عند تمرير هذه البنية إلى xrSetGoogleCloudAuthAsyncANDROID، يجب أن يكون العضو apiKey سلسلة ASCII غير فارغة بدون مسافات أو أحرف تحكّم، وإلا يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE .

يجب أن يستوفي apiKey الشروط التالية أيضًا:

  • يجب أن يكون مفتاح واجهة برمجة تطبيقات صالحًا تم إنشاؤه لمشروعك على Google Cloud.
  • يجب أن يفعّل مشروعك على السحابة الإلكترونية على Google Cloud واجهات Google Cloud API ذات الصلة (التي تحدّدها الإضافات التابعة).
  • إذا كان مفتاح واجهة برمجة التطبيقات يتضمّن قيودًا، يجب أن تسمح القيود بواجهات Google Cloud APIs ذات الصلة وبتطبيقك.

وإلا، سيتم تنفيذ طلب xrSetGoogleCloudAuthAsyncANDROID بنجاح، ولكن جميع الطلبات إلى الدوال التي تعتمد على التفويض في السحابة الإلكترونية ستعمل كما هو موضّح في حالات تعذُّر الاتصال بالسحابة الإلكترونية في الإضافة التي تحدّد هذه الدوال. إذا كان بإمكان دالة الإبلاغ عن تعذُّر تنفيذها وربط التطبيق XrGoogleCloudAuthErrorResultANDROID بمعلَمة الإخراج لتلك الدالة، يجب أن يضبط وقت التشغيل XrGoogleCloudAuthErrorResultANDROID :: error على XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID للإشارة إلى هذا الخطأ.

ستكتمل العملية غير المتزامنة مع XR_SUCCESS بعد التحقّق من تنسيق مفتاح واجهة برمجة التطبيقات وتخزينه من خلال وقت التشغيل.

الاستخدام الصالح (ضمني)

يتم تحديد بنية 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 واجهات Google Cloud API ذات الصلة (التي تحدّدها الإضافات التابعة).

  • يجب أن تكون بيانات الاعتماد واحدة مما يلي:

    • رمز دخول OAuth2 مع النطاقات ذات الصلة، يتم إنشاؤه من خلال تسجيل الدخول إلى حساب Google باستخدام تطبيقك، أو
    • رمز 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، قد ينشئ وقت التشغيل بيانات الاعتماد ديناميكيًا (على سبيل المثال، في Android، يتواصل وقت التشغيل مع "خدمات Google Play" من عملية التطبيق). إذا لم يتم إعداد "المصادقة بدون مفتاح" بشكل صحيح، قد يعرض وقت التشغيل XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID بشكل متزامن.

ستنفّذ العملية غير المتزامنة طلبات الشبكة اللازمة لاسترجاع بيانات الاعتماد. سيتم عرض نتيجة هذه العملية في XrFutureCompletionEXT :: futureResult من xrSetGoogleCloudAuthCompleteANDROID . إذا كانت النتيجة المستقبلية هي XR_SUCCESS، يعني ذلك أنّه تم تطبيق بيانات اعتماد "المصادقة بدون مفتاح" بنجاح. إذا كانت النتيجة المستقبلية هي XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID، قد يحاول التطبيق مرة أخرى لاحقًا.

الاستخدام الصالح (ضمني)

يتم تعريف الدالة 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 مؤشرًا إلى بنية يحدّد فيها العضو type في XrGoogleCloudAuthInfoBaseHeaderANDROID طريقة المصادقة التي سيتم استخدامها، والتي تمدّد XrGoogleCloudAuthInfoBaseHeaderANDROID (مثل XrGoogleCloudAuthInfoApiKeyANDROID).

يتم وصف المتطلبات والسلوكيات وحالات الخطأ المحددة (المتزامنة وغير المتزامنة) لكل طريقة مصادقة في مستندات هياكل البيانات الخاصة بها.

الاستخدام الصالح (ضمني)

رموز الإرجاع

Success

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

Success

  • XR_SUCCESS : تم تطبيق بيانات الاعتماد بنجاح.

تعذّر الإجراء

  • ‫XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : تعذّرت المصادقة بدون مفتاح. يمكن للتطبيق إعادة المحاولة لاحقًا. قد يتحقّق التطبيق أو المطوّر أيضًا من بعض الشروط المسبقة لنجاح العملية (على سبيل المثال، على أجهزة Android، يجب أن يكون لدى الجهاز إصدار حديث من "خدمات Google Play" ويجب أن تعمل هذه الخدمات بشكل صحيح).

الاستخدام الصالح (ضمني)

رموز الإرجاع

Success

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

تحتوي التعدادات على القيم التالية:

وصف التعداد

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، قد يتم ربط هذه البنية ببنية نتيجة العملية لتوفير مزيد من المعلومات حول الخطأ.

الاستخدام الصالح (ضمني)

مثال على الشفرة

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

الأوامر الجديدة

منشآت جديدة

عمليات تعداد جديدة

ثوابت تعداد جديدة

  • 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 (بن كينغ)

    • وصف الإضافة الأوّلي