Cloud SQL에 연결

BigQuery 관리자는 Cloud SQL 데이터에 액세스하기 위한 연결을 만들 수 있습니다. 데이터 분석가는 이 연결을 사용하여 Cloud SQL의 데이터를 쿼리할 수 있습니다. Cloud SQL에 연결하려면 다음 단계를 따라야 합니다.

Cloud SQL 연결 만들기
BigQuery Connection Service 에이전트에 액세스 권한 부여

시작하기 전에

Cloud SQL 데이터베이스가 포함된 프로젝트를 선택합니다.

프로젝트 선택기로 이동
BigQuery Connection API를 사용 설정합니다.

API 사용 설정하기
Cloud SQL 인스턴스에 공개 IP 연결 또는 비공개 연결이 있는지 확인합니다.
- Cloud SQL 인스턴스를 보호하려면 승인된 주소 없이 공개 IP 연결을 추가하면 됩니다. 이렇게 하면 공개 인터넷에서 인스턴스에 액세스할 수 없지만 BigQuery에서 쿼리할 수 있습니다.
- BigQuery가 비공개 연결을 통해 Cloud SQL 데이터에 액세스하도록 허용하려면 신규 또는 기존 Cloud SQL 인스턴스의 비공개 IP 연결을 구성한 다음 Google Cloud 서비스의 비공개 경로 체크박스를 선택합니다. 이 서비스는 Virtual Private Cloud 내의 비공개 IP 주소 대신 내부 직접 경로를 사용합니다.
Cloud SQL 연결을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 BigQuery 연결 관리자(roles/bigquery.connectionAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Cloud SQL 연결 만들기

Cloud SQL에 연결할 때 연결을 사용하여 데이터베이스 사용자 인증 정보를 처리하는 것이 좋습니다. 연결은 암호화되어 BigQuery 연결 서비스에 안전하게 저장됩니다. 사용자 인증 정보가 소스의 다른 데이터에 대해서도 유효하면 같은 연결을 다시 사용할 수 있습니다. 예를 들어 하나의 연결을 사용하여 동일한 Cloud SQL 인스턴스에 있는 여러 데이터베이스를 쿼리할 수 있습니다.

다음 옵션 중 하나를 선택하여 Cloud SQL 연결을 만드세요.

콘솔

BigQuery 페이지로 이동합니다.

BigQuery로 이동
탐색기 창에서 데이터 추가를 클릭합니다.
데이터 추가 대화상자에서 외부 데이터 소스에 연결을 클릭합니다.
외부 데이터 소스 대화상자에서 다음 정보를 입력합니다.
- 연결 유형에 대해 MySQL 또는 Postgres와 같은 소스 유형을 선택합니다.
- 연결 ID에는 연결 리소스의 식별자를 입력합니다. 문자, 숫자, 밑줄을 사용할 수 있습니다. 예를 들면 bq_sql_connection입니다.
- 데이터 위치에서 외부 데이터 소스 리전과 호환되는 BigQuery 위치(또는 리전)를 선택합니다.
- 선택사항: 별칭에 사용자 친화적인 연결 이름(예: My connection resource)을 입력합니다. 사용자 친화적인 이름으로 나중에 수정해야 하는 경우 연결 리소스를 식별하는 데 도움이 되는 모든 값을 사용할 수 있습니다.
- 선택사항: 설명에 이 연결 리소스에 대한 설명을 입력합니다.
- 선택사항: 암호화 고객 관리 암호화 키(CMEK)를 사용하여 사용자 인증 정보를 암호화하려면 고객 관리 암호화 키(CMEK)를 선택한 다음 고객 관리 키를 선택합니다. 그렇지 않으면 사용자 인증 정보가 기본 Google 소유 키 및 Google 관리 키로 보호됩니다.
- 연결 유형으로 Cloud SQL MySQL 또는 Postgres를 선택한 경우 Cloud SQL 연결 이름에 대해 Cloud SQL 인스턴스의 전체 이름을 일반적으로 project-id:location-id:instance-id 형식으로 입력합니다. 쿼리하려는 Cloud SQL 인스턴스의 세부정보 페이지에서 인스턴스 ID를 찾을 수 있습니다.
- 데이터베이스 이름에 데이터베이스 이름을 입력합니다.
- 데이터베이스 사용자 이름에 데이터베이스의 사용자 이름을 입력합니다.
- 데이터베이스 비밀번호에 데이터베이스의 비밀번호를 입력합니다.
  - 선택사항: 비밀번호를 보려면 비밀번호 표시를 클릭합니다.
  참고: 동일한 사용자 인증 정보가 외부 데이터 소스의 다른 데이터베이스에 유효한 경우 이 사용자는 동일한 연결 리소스를 통해 해당 데이터베이스를 쿼리할 수 있습니다.
연결 만들기를 클릭합니다.
연결로 이동을 클릭합니다.
연결 정보 창에서 다음 단계에 사용할 서비스 계정 ID를 복사합니다.

bq

bq mk 명령어를 입력하고 연결 플래그 --connection을 지정합니다. 다음 플래그도 필요합니다.

--connection_type
--properties
--connection_credential
--project_id
--location

다음 플래그는 선택사항입니다.

--display_name 연결의 별칭입니다.
--description 연결에 대한 설명입니다.

connection_id는 스토리지에 사용되는 명령어의 마지막 인수로 추가할 수 있는 선택적 매개변수입니다. 연결 ID가 제공되지 않으면 고유 ID가 자동으로 생성됩니다. connection_id에는 문자, 숫자, 밑줄이 포함될 수 있습니다.

    bq mk --connection --display_name='friendly name' --connection_type=TYPE \
      --properties=PROPERTIES --connection_credential=CREDENTIALS \
      --project_id=PROJECT_ID --location=LOCATION \
      CONNECTION_ID

다음을 바꿉니다.

TYPE: 외부 데이터 소스의 유형입니다.
PROPERTIES: JSON 형식의 생성된 연결의 매개변수입니다. 예를 들면 --properties='{"param":"param_value"}'입니다. 연결 리소스 생성에는 instanceID, database, type 매개변수를 지정해야 합니다.
CREDENTIALS: 매개변수 username 및 password입니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: Cloud SQL 인스턴스가 위치한 리전입니다.
CONNECTION_ID: 연결 식별자입니다.

예를 들어 다음 명령어를 실행하면 프로젝트에 ID가 federation-test인 my_new_connection(별칭: "My new connection")이라는 새 연결 리소스가 생성됩니다.

bq mk --connection --display_name='friendly name' --connection_type='CLOUD_SQL' \
  --properties='{"instanceId":"federation-test:us-central1:mytestsql","database":"mydatabase","type":"MYSQL"}' \
  --connection_credential='{"username":"myusername", "password":"mypassword"}' \
  --project_id=federation-test --location=us my_connection_id

API

BigQuery 연결 API 내에서 ConnectionService 내에서 CreateConnection를 호출하여 연결을 인스턴스화할 수 있습니다. 자세한 내용은 클라이언트 라이브러리 페이지를 참조하세요.

자바

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

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

import com.google.cloud.bigquery.connection.v1.CloudSqlCredential;
import com.google.cloud.bigquery.connection.v1.CloudSqlProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to create a connection with cloud MySql database
public class CreateConnection {

  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";
    String database = "MY_DATABASE";
    String instance = "MY_INSTANCE";
    String instanceLocation = "MY_INSTANCE_LOCATION";
    String username = "MY_USERNAME";
    String password = "MY_PASSWORD";
    String instanceId = String.format("%s:%s:%s", projectId, instanceLocation, instance);
    CloudSqlCredential cloudSqlCredential =
        CloudSqlCredential.newBuilder().setUsername(username).setPassword(password).build();
    CloudSqlProperties cloudSqlProperties =
        CloudSqlProperties.newBuilder()
            .setType(CloudSqlProperties.DatabaseType.MYSQL)
            .setDatabase(database)
            .setInstanceId(instanceId)
            .setCredential(cloudSqlCredential)
            .build();
    Connection connection = Connection.newBuilder().setCloudSql(cloudSqlProperties).build();
    createConnection(projectId, location, connectionId, connection);
  }

  static void createConnection(
      String projectId, String location, String connectionId, Connection connection)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      LocationName parent = LocationName.of(projectId, location);
      CreateConnectionRequest request =
          CreateConnectionRequest.newBuilder()
              .setParent(parent.toString())
              .setConnection(connection)
              .setConnectionId(connectionId)
              .build();
      Connection response = client.createConnection(request);
      System.out.println("Connection created successfully :" + response.getName());
    }
  }
}

서비스 계정에 액세스 권한 부여

프로젝트 내에서 Cloud SQL에 대한 첫 번째 연결을 만들면 서비스 계정이 자동으로 생성됩니다. 서비스 계정의 이름은 BigQuery Connection 서비스 에이전트입니다. 서비스 계정 ID를 가져오려면 연결 세부정보를 확인합니다. 서비스 계정 ID의 형식은 다음과 같습니다.

service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com.

Cloud SQL에 연결하려면 BigQuery가 사용자를 대신하여 파일에 액세스할 수 있도록 새 연결에 Cloud SQL에 대한 읽기 전용 액세스 권한을 부여해야 합니다. 이 서비스 계정에는 다음 권한이 있어야 합니다.

cloudsql.instances.connect
cloudsql.instances.get

이러한 권한과 함께 Cloud SQL 클라이언트 IAM 역할(roles/cloudsql.client)을 연결된 서비스 계정에 부여할 수 있습니다. 서비스 계정에 이미 필요한 권한이 있으면 이 단계를 생략할 수 있습니다.

콘솔

IAM 및 관리자 페이지로 이동합니다.

IAM 및 관리자로 이동
액세스 권한 부여를 클릭합니다.

주 구성원 추가 대화상자가 열립니다.
새 주 구성원 필드에 서비스 계정 이름 BigQuery Connection Service 에이전트 또는 연결 정보에서 가져온 서비스 계정 ID를 입력합니다.
역할 선택 필드에서 Cloud SQL을 선택한 후 Cloud SQL 클라이언트를 선택합니다.
저장을 클릭합니다.

gcloud

gcloud projects add-iam-policy-binding 명령어를 사용합니다.

gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:SERVICE_ACCOUNT_ID --role=roles/cloudsql.client

다음 값을 제공합니다.

PROJECT_ID: Google Cloud 프로젝트 ID
SERVICE_ACCOUNT_ID: 연결 정보에서 가져온 서비스 계정 ID

사용자와 연결 공유

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

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

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

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

콘솔

BigQuery 페이지로 이동합니다.

BigQuery로 이동

이러한 연결은 프로젝트의 외부 연결 그룹에 나열됩니다.
탐색기 창에서 프로젝트 이름 > 외부 연결 > 연결을 클릭합니다.
세부정보 창에서 공유를 클릭하여 연결을 공유합니다. 다음 작업을 수행합니다.
1. 연결 권한 대화상자에서 주 구성원을 추가하거나 수정하여 다른 주 구성원과 연결을 공유합니다.
2. 저장을 클릭합니다.

bq

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

API

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

자바

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");
    }
  }
}

다음 단계

다양한 연결 유형 알아보기
연결 관리 알아보기
통합 쿼리 알아보기
Cloud SQL 데이터 쿼리 방법 알아보기