XR_ANDROID_google_cloud_auth

이름 문자열

XR_ANDROID_google_cloud_auth

확장 프로그램 유형

인스턴스 확장

등록된 내선 번호

788

버전

1

비준 상태

비준되지 않음

확장 프로그램 및 버전 종속 항목

XR_EXT_future

최종 수정일

2025-12-18

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

존 울먼, Google
벤 킹, Google
니하브 제인, Google
제러드 파인더, Google

개요

이 확장 프로그램은 애플리케이션이 Google Cloud API의 인증 사용자 인증 정보를 제공하도록 허용하여 Google Cloud 기반 확장 프로그램의 사용을 지원합니다. 개발자는 Google Cloud 콘솔 ( https://console.cloud.google.com/)을 사용하여 애플리케이션의 Google Cloud 프로젝트를 만들어야 합니다. 이 확장 프로그램에는 XR_EXT_future 확장 프로그램이 필요합니다 .

개발 중에 애플리케이션은 확장 프로그램 XR_EXT_debug_utils 를 사용하여 Google Cloud 설정 문제를 디버그할 수 있습니다 . 애플리케이션에 디버그 메신저가 있고 애플리케이션을 대신하여 Google Cloud에 요청을 보낼 때 런타임에서 조치를 취할 수 있는 오류가 발생하면 런타임은 오류 메시지와 함께 메신저의 콜백을 호출합니다. 이 경우 개발자는 오류 메시지와 사용 가능한 모든 문서를 참고한 후 애플리케이션과 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와 함께 사용하여 인증 사용자 인증 정보를 제공할 수 있는 다른 구조에 의해 확장됩니다.

유효한 사용 (암시적)

• XrGoogleCloudAuthInfoBaseHeaderANDROID를 사용하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• 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는 다음 조건을 추가로 충족해야 합니다.

• Google Cloud 프로젝트에 대해 생성된 유효한 API 키여야 합니다.
• Google Cloud 프로젝트에서 관련 Google Cloud API (종속 확장 프로그램에 의해 지정됨)를 사용 설정해야 합니다.
• API 키에 제한사항이 있는 경우 제한사항이 관련 Google Cloud API와 애플리케이션을 허용해야 합니다.

그렇지 않으면 xrSetGoogleCloudAuthAsyncANDROID 호출은 성공하지만 클라우드 승인에 종속된 함수에 대한 모든 호출은 이러한 함수를 정의하는 확장 프로그램의 클라우드 실패에 대해 문서화된 대로 작동합니다. 함수가 실패를 보고할 수 있고 애플리케이션이 XrGoogleCloudAuthErrorResultANDROID를 해당 함수의 출력 매개변수에 연결하는 경우 런타임은 이 오류를 나타내기 위해 XrGoogleCloudAuthErrorResultANDROID :: error를 XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID로 설정해야 합니다.

API 키의 형식이 검증되고 런타임에 저장되면 비동기 작업이 XR_SUCCESS로 완료됩니다.

유효한 사용 (암시적)

• XrGoogleCloudAuthInfoApiKeyANDROID를 사용하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• type은 XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID이어야 합니다.
• next은 NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다.
• apiKey은 널 종료 UTF-8 문자열이어야 합니다(must).

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 (종속 확장 프로그램에 의해 지정됨)를 사용 설정해야 합니다.

• 인증 정보는 다음 중 하나여야 합니다.

  • 애플리케이션으로 Google 계정에 로그인하여 생성된 관련 범위가 있는 OAuth2 액세스 토큰
  • Google Cloud 프로젝트의 서비스 계정에서 생성된 관련 클레임이 포함된 서명된 JWT 토큰

각 사례의 요구사항은 종속 확장 프로그램에 의해 지정됩니다. 그렇지 않으면 xrSetGoogleCloudAuthAsyncANDROID 호출은 성공하지만 클라우드 승인에 종속된 함수에 대한 모든 호출은 이러한 함수를 정의하는 확장 프로그램의 클라우드 실패에 대해 문서화된 대로 작동합니다. 함수가 실패를 보고할 수 있고 애플리케이션이 XrGoogleCloudAuthErrorResultANDROID를 해당 함수의 출력 매개변수에 연결하는 경우 런타임은 이 오류를 나타내기 위해 XrGoogleCloudAuthErrorResultANDROID :: error를 XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID로 설정해야 합니다.

애플리케이션은 이전 토큰이 만료되기 전에 xrSetGoogleCloudAuthAsyncANDROID를 통해 새 토큰을 적극적으로 전달해야 합니다. 런타임은 새 네트워크 요청을 시작할 때 애플리케이션에서 전달한 최신 토큰을 사용해야 합니다.

토큰의 형식이 검증되고 런타임에 의해 저장되면 비동기 작업이 XR_SUCCESS로 완료됩니다.

유효한 사용 (암시적)

• XrGoogleCloudAuthInfoTokenANDROID를 사용하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• type은 XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID이어야 합니다.
• next은 NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다.
• authToken은 널 종료 UTF-8 문자열이어야 합니다(must).

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를 동기적으로 반환할 수 있습니다.

비동기 작업은 사용자 인증 정보를 가져오기 위해 필요한 네트워크 요청을 실행합니다. 이 작업의 결과는 xrSetGoogleCloudAuthCompleteANDROID에서 XrFutureCompletionEXT :: futureResult로 반환됩니다 . 향후 결과가 XR_SUCCESS이면 키리스 인증 사용자 인증 정보가 성공적으로 적용된 것입니다. 향후 결과가 XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID인 경우 애플리케이션이 나중에 다시 시도할 수 있습니다.

유효한 사용 (암시적)

• XrGoogleCloudAuthInfoKeylessANDROID를 사용하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• 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_SUCCESS를 반환하지 않은 경우 XR_NULL_HANDLE입니다 .

Google Cloud로 인증하는 데 사용되는 사용자 인증 정보를 설정합니다. 이 작업은 비동기식입니다. xrPollFutureEXT를 호출하여 미래의 준비 상태를 확인합니다. 퓨처가 준비 상태가 되면 xrSetGoogleCloudAuthCompleteANDROID를 호출하여 결과를 가져옵니다.

authInfo 매개변수는 사용할 인증 방법을 식별하고 XrGoogleCloudAuthInfoBaseHeaderANDROID를 확장하는 구조체 (예: XrGoogleCloudAuthInfoApiKeyANDROID)에 대한 포인터여야 합니다.type

각 인증 방법의 구체적인 요구사항, 동작, 오류 조건 (동기 및 비동기)은 각 데이터 구조의 문서에 설명되어 있습니다.

유효한 사용 (암시적)

• xrSetGoogleCloudAuthAsyncANDROID를 호출하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• session은 유효한 XrSession 핸들이어야 합니다.
• authInfo은 유효한 XrGoogleCloudAuthInfoBaseHeaderANDROID 기반 구조를 가리키는 포인터여야 합니다. 참고: XrGoogleCloudAuthInfoApiKeyANDROID , XrGoogleCloudAuthInfoKeylessANDROID , XrGoogleCloudAuthInfoTokenANDROID
• future은 XrFutureEXT 값에 대한 포인터여야 합니다.

반환 코드

성공

• 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 서비스가 설치되어 있어야 하고 이러한 서비스가 제대로 작동해야 함)을 확인할 수도 있습니다.

유효한 사용 (암시적)

• xrSetGoogleCloudAuthCompleteANDROID를 호출하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• session은 유효한 XrSession 핸들이어야 합니다.
• completion는 XrFutureCompletionEXT 구조체에 대한 포인터여야 합니다.

반환 코드

성공

• 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는 Google Cloud에 액세스하는 작업의 오류 원인을 자세히 설명하는 XrGoogleCloudAuthErrorANDROID입니다.

Google Cloud 인증으로 인해 작업이 실패하는 경우 이 구조체는 오류에 관한 자세한 정보를 제공하기 위해 작업 결과 구조체에 연결될 수 있습니다.

유효한 사용 (암시적)

• XrGoogleCloudAuthErrorResultANDROID를 사용하기 전에 XR_ANDROID_google_cloud_auth 확장 프로그램을 사용 설정해야 합니다.
• 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

새 열거형

• XrGoogleCloudAuthErrorANDROID

새 열거형 상수

• 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일 (벤 킹)

  • 초기 확장 프로그램 설명입니다.