XR_ANDROID_google_cloud_auth

Chuỗi tên

XR_ANDROID_google_cloud_auth

Loại tiện ích

Tiện ích thực thể

Số tiện ích đã đăng ký

788

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa phê chuẩn

Tiện ích và các phần phụ thuộc vào phiên bản

XR_EXT_future

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

2025-12-18

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu IP nào được biết.

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 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 đề với thiết lập Google Cloud bằng cách sử dụng tiện ích XR_EXT_debug_utils . Nếu ứng dụng có một Trình gửi thông báo gỡ lỗi và một lỗi có thể thực hiện được sẽ xảy ra 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ửi thông báo bằng một 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 các Cloud APIs của Google. 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 xác định như sau:

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

Mô tả thành phần

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc một 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 sử dụng trực tiếp trong API nhưng được mở rộng bởi các cấu trúc khác có thể được sử dụng với xrSetGoogleCloudAuthAsyncANDROID để cung cấp thông tin xác thực.

Cách sử dụng hợp lệ (ngụ ý)

Cấu trúc XrGoogleCloudAuthInfoApiKeyANDROID được xác định như sau:

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

Mô tả thành phần

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc một con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • apiKey là một con trỏ trỏ đến một 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 Cloud API có liên quan của Google (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 API có liên quan của Google 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 việc uỷ quyền trên đám mây sẽ hoạt động như được ghi lại đối với 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 xích XrGoogleCloudAuthErrorResultANDROID vào 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 với XR_SUCCESS sau khi khoá API được xác thực về định dạng và được thời gian chạy lưu trữ.

Cách sử dụng hợp lệ (ngụ ý)

Cấu trúc XrGoogleCloudAuthInfoTokenANDROID được xác định như sau:

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

Mô tả thành phần

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc một con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • authToken là một con trỏ 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:

  • Đây phải là một thông tin xác thực hợp lệ và chưa hết hạn được tạo cho dự án Google Cloud của bạn.
  • Dự án Google Cloud của bạn phải bật các Cloud API có liên quan của Google (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ó cá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 báo xác nhận quyền sở hữu liên quan, được tạo bởi một Tài khoản dịch vụ từ dự án trên đám mây của Google Cloud của bạn.

Các 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 việc uỷ quyền trên đám mây sẽ hoạt động như được ghi lại đối với 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 xích XrGoogleCloudAuthErrorResultANDROID vào 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 thời gian chạy lưu trữ.

Cách sử dụng hợp lệ (ngụ ý)

Cấu trúc XrGoogleCloudAuthInfoKeylessANDROID được xác định như sau:

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

Mô tả thành phần

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc một 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 ứng dụng). Nếu tính năng Xác thực không cần khoá không được thiết lập đúng cách, 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 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ụ ý)

Hàm xrSetGoogleCloudAuthAsyncANDROID được xác định như sau:

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

Mô tả tham số

  • session là XrSession sẽ sử dụng thông tin xác thực.
  • authInfo là một con trỏ trỏ đến một cấu trúc chỉ định phương thức và tham số xác thực, với trường XrGoogleCloudAuthInfoBaseHeaderANDROID :: type cho biết cấu trúc cụ thể.
  • future là một con trỏ trỏ đến một trình xử lý XrFutureEXT trong đó tương lai đã tạo đượ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 là không đồng bộ. Gọi xrPollFutureEXT để kiểm tra trạng thái sẵn sàng trên tương lai. Sau khi tương lai ở 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ỏ trỏ đến một cấu trúc mà thành phần XrGoogleCloudAuthInfoBaseHeaderANDROID :: type xác định phương thức 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 thức xác thực được mô tả trong tài liệu về các cấu trúc dữ liệu tương ứng.

Cách sử dụng hợp lệ (ngụ ý)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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 xác định như sau:

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

Mô tả tham số

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

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

XrFutureCompletionEXT :: futureResult giá trị:

Thành công

  • XR_SUCCESS : Thông tin xác thực đã được áp dụng thành công.

Thất bại

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Xác thực không cần khoá không thành công. Ứ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 để thành công (ví dụ: trên Android, thiết bị phải cài đặt Dịch vụ Google Play phiên bản mới nhất và các dịch vụ này phải hoạt động đúng cách).

Cách sử dụng hợp lệ (ngụ ý)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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

Liệt kê XrGoogleCloudAuthErrorANDROID được xác định 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:

Mô tả enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

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

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

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

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Không kết nối được với một API của Google Cloud, có thể là do sự cố về khả năng kết nối mạng hoặc tình trạng sẵn có 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 của Google Cloud.

Cấu trúc XrGoogleCloudAuthErrorResultANDROID được xác định như sau:

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

Mô tả thành phần

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc một 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 Xác thực Google Cloud, thì cấu trúc này có thể được xích vào 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ã 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)

    • Mô tả tiện ích ban đầu.