Spanner에 연결

BigQuery 관리자는 Spanner 데이터 액세스를 위한 연결을 만들 수 있습니다. 이 연결을 사용하면 데이터 분석가는 Spanner에서 데이터를 쿼리할 수 있습니다.

시작하기 전에

Spanner 연결 만들기

다음 옵션 중 하나를 선택합니다.

콘솔

  1. BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 데이터 추가 메뉴에서 외부 데이터 소스에 연결을 선택합니다.

  3. 외부 데이터 소스 창에서 다음 정보를 입력합니다.

    • 연결 유형에 Spanner를 선택합니다.
    • 연결 ID에는 연결 리소스의 식별자를 입력합니다. 문자, 숫자, 밑줄을 사용할 수 있습니다.
    • 데이터 위치에서 외부 데이터 소스 리전과 호환되는 BigQuery 위치(또는 리전)를 선택합니다.
    • 선택사항: 별칭에 사용자 친화적인 연결 이름(예: My connection resource)을 입력합니다. 사용자 친화적인 이름으로 나중에 수정해야 하는 경우 연결 리소스를 식별하는 데 도움이 되는 모든 값을 사용할 수 있습니다.
    • 선택사항: 설명에 이 연결 리소스에 대한 설명을 입력합니다.
    • 데이터베이스 이름에 Spanner 데이터베이스를 "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE" 형식으로 입력합니다.
    • 선택사항: 병렬 읽기를 수행하려면 동시에 데이터 읽기를 선택합니다. Spanner에서는 특정 쿼리를 더 작은 부분이나 파티션 여러 개로 나누고 파티션을 동시에 가져올 수 있습니다. 자세한 내용은 Spanner 문서의 동시에 데이터 읽기를 참조하세요. 이 옵션은 실행 계획의 첫 번째 연산자가 분산 통합 연산자인 쿼리로 제한됩니다. 다른 쿼리는 오류를 반환합니다. Spanner 쿼리의 쿼리 실행 계획을 보려면 Spanner의 쿼리 실행 방법 이해를 참조하세요.
    • 선택사항: 데이터베이스 역할에 Spanner 데이터베이스 역할의 이름을 입력합니다. 비어 있지 않은 경우 이 연결은 기본적으로 이 데이터베이스 역할을 사용하여 Spanner를 쿼리합니다. 이 연결을 통해 쿼리를 제출하는 세분화된 액세스 제어 사용자는 관리자로부터 이 역할에 대한 액세스 권한을 부여받아야 하며, 데이터베이스 역할에는 외부 쿼리에 지정된 모든 스키마 객체에 대한 SELECT 권한이 있어야 합니다. 세분화된 액세스 제어에 대한 자세한 내용은 세분화된 액세스 제어 정보를 참조하세요.
    • 선택사항: Data Boost를 사용 설정하려면 Data Boost를 선택합니다. Data Boost를 사용하면 프로비저닝된 BigQuery 인스턴스의 기존 워크로드에 거의 영향을 주지 않고 분석 쿼리 및 데이터 내보내기를 실행할 수 있습니다. Data Boost를 사용 설정하려면 Data Boost 및 데이터 병렬로 읽기를 선택합니다.

  4. 연결 만들기를 클릭합니다.

bq

연결을 만들려면 --connection 플래그와 함께 bq mk 명령어를 사용합니다.

bq mk --connection \
    --connection_type=CLOUD_SPANNER \
    --properties='PROPERTIES' \
    --location=LOCATION \
    --display_name='FRIENDLY_NAME' \
    --description 'DESCRIPTION' \
    CONNECTION_ID

다음을 바꿉니다.

  • PROPERTIES: 다음 필드가 있는 JSON 객체입니다.

    • "database": 연결에 사용되는 Spanner 데이터베이스입니다.

      "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE" 형식의 문자열로 지정합니다.

    • "use_parallelism": (선택사항) true인 경우 이 연결은 병렬 읽기를 수행합니다.

      기본값은 false입니다. Spanner에서는 특정 쿼리를 더 작은 부분이나 파티션 여러 개로 나누고 파티션을 동시에 가져올 수 있습니다. 자세한 내용은 Spanner 문서의 동시에 데이터 읽기를 참조하세요. 이 옵션은 실행 계획의 첫 번째 연산자가 분산 통합 연산자인 쿼리로 제한됩니다. 다른 쿼리는 오류를 반환합니다. Spanner 쿼리의 쿼리 실행 계획을 보려면 Spanner의 쿼리 실행 방법 이해를 참조하세요.

    • "database_role": (선택사항) 비어 있지 않은 경우 이 연결은 기본적으로 이 데이터베이스 역할을 사용하여 Spanner를 쿼리합니다. 이 연결을 통해 쿼리를 제출하는 세분화된 액세스 제어 사용자는 관리자로부터 이 역할에 대한 액세스 권한을 부여받아야 하며, 데이터베이스 역할에는 외부 쿼리에 지정된 모든 스키마 객체에 대한 SELECT 권한이 있어야 합니다.

      지정되지 않은 경우 이 연결은 Spanner에 대한 사전 정의된 IAM 역할로 인증되며 이 연결로 쿼리를 실행하는 주 구성원에게 roles/spanner.databaseReader IAM 역할을 부여해야 합니다.

      세분화된 액세스 제어에 대한 자세한 내용은 세분화된 액세스 제어 정보를 참조하세요.

    • "useDataBoost": (선택사항) true인 경우 이 연결을 통해 Data Boost를 사용할 수 있습니다. Data Boost를 사용하면 사용자는 프로비저닝된 인스턴스와 다른 별도의 독립적인 컴퓨팅 용량에서 통합 쿼리를 실행하여 기존 워크로드에 영향을 주지 않도록 할 수 있습니다. Data Boost를 사용 설정하려면 "useDataBoost"를 true로, "use_parallelism"을 true로 설정합니다.

      Data Boost를 사용하려면 이 연결로 쿼리를 실행하는 주 구성원에게 spanner.databases.useDataBoost 권한이 부여되어야 합니다. 이 권한은 기본적으로 roles/spanner.admin 및 roles/spanner.databaseAdmin 역할에 포함되어 있습니다.

  • LOCATION: 외부 데이터 소스 리전과 호환되는 BigQuery 위치입니다.

  • CONNECTION_ID: 연결 리소스의 식별자입니다.

    연결 ID에는 문자, 숫자, 밑줄이 포함될 수 있습니다. 연결 ID를 제공하지 않으면 BigQuery에서 자동으로 고유 ID를 생성합니다.

    다음 예시에서는 my_connection_id라는 새 연결 리소스를 만듭니다.

    bq mk --connection \
  --connection_type='CLOUD_SPANNER' \
  --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \
  --project_id=federation-test \
  --location=us \
  my_connection_id

API

ConnectionService 서비스 내에서 CreateConnection 메서드를 호출합니다.

사용자와 연결 공유

데이터를 쿼리하고 연결을 관리할 수 있도록 사용자에게 다음 역할을 부여할 수 있습니다.

  • roles/bigquery.connectionUser: 사용자가 연결을 사용하여 외부 데이터 소스에 연결하고 쿼리를 실행할 수 있습니다.

  • roles/bigquery.connectionAdmin: 사용자가 연결을 관리할 수 있습니다.

BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

다음 옵션 중 하나를 선택합니다.

콘솔

  1. BigQuery 페이지로 이동합니다.

    BigQuery로 이동

    이러한 연결은 프로젝트의 외부 연결 그룹에 나열됩니다.

  2. 탐색기 창에서 프로젝트 이름 > 외부 연결 > 연결을 클릭합니다.

  3. 세부정보 창에서 공유를 클릭하여 연결을 공유합니다. 다음 작업을 수행합니다.

    1. 연결 권한 대화상자에서 주 구성원을 추가하거나 수정하여 다른 주 구성원과 연결을 공유합니다.

    2. 저장을 클릭합니다.

bq

bq 명령줄 도구로 연결을 공유할 수 없습니다. 연결을 공유하려면 Google Cloud 콘솔 또는 BigQuery Connections API 메서드를 사용하여 연결을 공유합니다.

API

BigQuery 연결 REST API 참조 섹션의 projects.locations.connections.setIAM 메서드를 사용하고 policy 리소스의 인스턴스를 지정합니다.

Java

이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요. 

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

다음 단계