XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

788

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần phụ thuộc của tiện ích và phiên bản

XR_EXT_future

Ngày sửa đổi gần đây nhất

2025-12-18

Trạng thái IP

Không có tuyên bố nào về tài sản trí tuệ.

Cộng tác viên

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

Tổng quan

Tiện ích này cho phép sử dụng các tiện ích dựa trên Google Cloud bằng cách cho phép ứng dụng cung cấp thông tin xác thực cho các API của Google Cloud. Nhà phát triển phải sử dụng Google Cloud Console ( https://console.cloud.google.com/ ) để tạo một dự án trên đám mây của Google Cloud cho ứng dụng. Tiện ích này yêu cầu tiện ích XR_EXT_future .

Trong quá trình phát triển, ứng dụng có thể gỡ lỗi các vấn đề liên quan đến việc thiết lập Google Cloud bằng tiện ích XR_EXT_debug_utils . Nếu ứng dụng có Trình gỡ lỗi và xảy ra lỗi có thể xử lý được trong thời gian chạy khi gửi yêu cầu đến Google Cloud thay mặt cho ứng dụng, thì thời gian chạy sẽ gọi lệnh gọi lại của trình gỡ lỗi kèm theo thông báo lỗi. Trong trường hợp này, nhà phát triển nên tham khảo thông báo lỗi và tất cả tài liệu hiện có, sau đó đảm bảo rằng ứng dụng và dự án Google Cloud được thiết lập đúng cách để sử dụng API Google Cloud. Môi trường thời gian chạy phải sử dụng loại thông báo XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT , mức độ nghiêm trọng XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT và messageId "GoogleCloudError".

Xác thực

Cấu trúc XrGoogleCloudAuthInfoBaseHeaderANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.

Cấu trúc này không được dùng trực tiếp trong API nhưng được mở rộng bằng các cấu trúc khác có thể dùng với xrSetGoogleCloudAuthAsyncANDROID để cung cấp thông tin xác thực.

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrGoogleCloudAuthInfoApiKeyANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • apiKey là một con trỏ đến chuỗi đại diện cho khoá API.

Khi cấu trúc này được truyền đến xrSetGoogleCloudAuthAsyncANDROID , thành phần apiKey phải là một chuỗi ASCII không trống, không có dấu cách hoặc ký tự điều khiển, nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

apiKey phải đáp ứng thêm các điều kiện sau:

  • Đây phải là một Khoá API hợp lệ được tạo cho dự án trên đám mây của Google Cloud của bạn.
  • Dự án Google Cloud của bạn phải bật các API Google Cloud có liên quan (do các tiện ích phụ thuộc chỉ định).
  • Nếu Khoá API có các quy tắc hạn chế, thì các quy tắc hạn chế đó phải cho phép các Cloud APIs của Google Cloud có liên quan và ứng dụng của bạn.

Nếu không, lệnh gọi đến xrSetGoogleCloudAuthAsyncANDROID sẽ thành công nhưng tất cả lệnh gọi đến các hàm phụ thuộc vào hoạt động uỷ quyền trên đám mây sẽ hoạt động như được ghi nhận cho các lỗi trên đám mây trong tiện ích xác định các hàm đó. Nếu một hàm có thể báo cáo lỗi và ứng dụng liên kết XrGoogleCloudAuthErrorResultANDROID với tham số đầu ra của hàm đó, thì thời gian chạy phải đặt XrGoogleCloudAuthErrorResultANDROID :: error thành XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID để cho biết lỗi này.

Thao tác không đồng bộ sẽ hoàn tất bằng XR_SUCCESS sau khi khoá API được xác thực về định dạng và được lưu trữ theo thời gian chạy.

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrGoogleCloudAuthInfoTokenANDROID được định nghĩa như sau:

typedef struct XrGoogleCloudAuthInfoTokenANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        authToken;
} XrGoogleCloudAuthInfoTokenANDROID;

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • authToken là con trỏ đến một chuỗi đại diện cho mã thông báo xác thực.

Khi cấu trúc này được truyền đến xrSetGoogleCloudAuthAsyncANDROID, thành phần authToken phải là một chuỗi ASCII không trống, không có dấu cách hoặc ký tự điều khiển, nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE . authToken phải đáp ứng thêm các điều kiện sau:

  • Thông tin xác thực này phải hợp lệ và chưa hết hạn, đồng thời được tạo cho dự án trên đám mây của bạn trên Google Cloud.
  • Dự án Google Cloud của bạn phải bật các API Google Cloud có liên quan (do các tiện ích phụ thuộc chỉ định).

  • Thông tin xác thực phải là một trong những thông tin sau:

    • Mã truy cập OAuth2 có phạm vi liên quan, được tạo bằng cách đăng nhập vào Tài khoản Google bằng ứng dụng của bạn, HOẶC
    • Mã thông báo JWT đã ký có các thông tin xác nhận quyền sở hữu liên quan, do một Tài khoản dịch vụ tạo từ dự án trên đám mây của bạn trên Google Cloud.

Yêu cầu trong mỗi trường hợp được chỉ định bởi các tiện ích phụ thuộc. Nếu không, lệnh gọi đến xrSetGoogleCloudAuthAsyncANDROID sẽ thành công nhưng tất cả lệnh gọi đến các hàm phụ thuộc vào hoạt động uỷ quyền trên đám mây sẽ hoạt động như được ghi nhận cho các lỗi trên đám mây trong tiện ích xác định các hàm đó. Nếu một hàm có thể báo cáo lỗi và ứng dụng liên kết XrGoogleCloudAuthErrorResultANDROID với tham số đầu ra của hàm đó, thì thời gian chạy phải đặt XrGoogleCloudAuthErrorResultANDROID :: error thành XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID để cho biết lỗi này.

Ứng dụng phải chủ động truyền mã thông báo mới thông qua xrSetGoogleCloudAuthAsyncANDROID trước khi mã thông báo cũ hết hạn. Thời gian chạy phải sử dụng mã thông báo mới nhất do ứng dụng truyền vào khi bắt đầu một yêu cầu mạng mới.

Thao tác không đồng bộ sẽ hoàn tất với XR_SUCCESS sau khi mã thông báo được xác thực về định dạng và được lưu trữ trong thời gian chạy.

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrGoogleCloudAuthInfoKeylessANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.

Khi cấu trúc này được truyền đến xrSetGoogleCloudAuthAsyncANDROID , thời gian chạy có thể tạo thông tin xác thực một cách linh động (ví dụ: trên Android, thời gian chạy giao tiếp với Dịch vụ Google Play từ quy trình của ứng dụng). Nếu bạn không thiết lập đúng cách tính năng Xác thực không cần khoá, thì thời gian chạy có thể trả về XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID một cách đồng bộ.

Thao tác không đồng bộ sẽ thực hiện các yêu cầu mạng cần thiết để tìm nạp thông tin xác thực. Kết quả của thao tác này sẽ được trả về trong XrFutureCompletionEXT :: futureResult từ xrSetGoogleCloudAuthCompleteANDROID . Nếu kết quả trong tương lai là XR_SUCCESS , thì thông tin xác thực của tính năng Xác thực không cần khoá đã được áp dụng thành công. Nếu kết quả trong tương lai là XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , thì ứng dụng có thể thử lại sau.

Cách sử dụng hợp lệ (Ngầm ẩn)

Hàm xrSetGoogleCloudAuthAsyncANDROID được định nghĩa như sau:

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

Nội dung mô tả về tham số

  • session là XrSession sẽ sử dụng thông tin xác thực.
  • authInfo là con trỏ đến một cấu trúc chỉ định phương pháp xác thực và tham số, trong đó trường XrGoogleCloudAuthInfoBaseHeaderANDROID :: type cho biết cấu trúc cụ thể.
  • future là con trỏ đến một tay điều khiển XrFutureEXT, trong đó kết quả được tạo sẽ được trả về hoặc XR_NULL_HANDLE nếu hàm không trả về XR_SUCCESS .

Đặt thông tin xác thực dùng để xác thực với Google Cloud. Thao tác này không đồng bộ. Gọi xrPollFutureEXT để kiểm tra trạng thái sẵn sàng trong tương lai. Sau khi đối tượng Future ở trạng thái sẵn sàng, hãy gọi xrSetGoogleCloudAuthCompleteANDROID để truy xuất kết quả.

Tham số authInfo phải là một con trỏ đến một cấu trúc có thành phần XrGoogleCloudAuthInfoBaseHeaderANDROID :: type xác định phương pháp xác thực sẽ được sử dụng và mở rộng XrGoogleCloudAuthInfoBaseHeaderANDROID (ví dụ: XrGoogleCloudAuthInfoApiKeyANDROID ).

Các yêu cầu, hành vi và điều kiện lỗi cụ thể (cả đồng bộ và không đồng bộ) cho từng phương pháp xác thực được mô tả trong tài liệu về cấu trúc dữ liệu tương ứng.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Hàm xrSetGoogleCloudAuthCompleteANDROID được định nghĩa như sau:

XrResult xrSetGoogleCloudAuthCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrFutureCompletionEXT*                      completion);

Nội dung mô tả về tham số

  • session là XrSession dùng để bắt đầu thao tác.
  • future là XrFutureEXT cần hoàn thành.
  • completion là một con trỏ đến XrFutureCompletionEXT do thời gian chạy điền vào.

Mã trả về trong tương lai

XrFutureCompletionEXT :: Giá trị futureResult:

Thành công

  • XR_SUCCESS : Đã áp dụng thành công thông tin đăng nhập.

Không thành công

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Không xác thực được bằng phương thức không dùng khoá. Ứng dụng có thể thử lại sau. Ứng dụng hoặc nhà phát triển cũng có thể kiểm tra một số điều kiện tiên quyết để đảm bảo thành công (ví dụ: trên Android, thiết bị phải cài đặt phiên bản mới nhất của Dịch vụ Google Play và các dịch vụ này phải hoạt động bình thường).

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Lỗi xác thực Google Cloud

Phép liệt kê XrGoogleCloudAuthErrorANDROID được định nghĩa như sau:

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;

Các giá trị liệt kê có các giá trị sau:

Nội dung mô tả enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Không xảy ra lỗi khi gọi một API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Đã vượt quá hạn mức khi gọi một API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Không kết nối được với một API Google Cloud, có thể là do vấn đề về kết nối mạng hoặc tình trạng sẵn sàng của máy chủ.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Đã xảy ra lỗi xác thực khi gọi một API Google Cloud.

Cấu trúc XrGoogleCloudAuthErrorResultANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • error là XrGoogleCloudAuthErrorANDROID nêu chi tiết nguyên nhân gây ra lỗi của một thao tác truy cập vào Google Cloud.

Nếu một thao tác không thành công do quy trình Xác thực Google Cloud, thì cấu trúc này có thể được liên kết với cấu trúc kết quả hoạt động để cung cấp thêm thông tin về lỗi.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã ví dụ

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

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số enum mới

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Mở rộng XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Mở rộng 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

Vấn đề

  • Bản sửa đổi 1, 18/12/2025 (Ben King)

    • Nội dung mô tả ban đầu về tiện ích.