커스텀 커넥터 만들기

이 페이지에서는 커스텀 커넥터를 만드는 방법을 설명합니다. 커스텀 커넥터의 정의에 대해서는 커스텀 커넥터를 참조하세요.

커스텀 커넥터를 사용하여 백엔드에 대한 연결을 설정하려면 다음 태스크를 수행해야 합니다.

커스텀 커넥터 만들기 - 이 태스크에서는 엔드포인트의 OpenAPI 사양을 제공하여 Integration Connectors와 엔드포인트(백엔드) 간의 계약을 정의합니다. 현재는 OpenAPI 버전 3.0과 해당 버전의 모든 부 버전만 지원됩니다. 사양은 한 번만 지정하면 됩니다.
커스텀 커넥터 연결 만들기 - 이 태스크에서는 호스트 이름 및 인증과 같은 백엔드의 연결 세부정보를 구성합니다. 특정 커스텀 커넥터에 필요한 만큼 연결을 만들 수 있습니다.

커넥터와 연결의 차이점을 이해하려면 커넥터와 연결 비교를 참조하세요.

시작하기 전에

커스텀 커넥터를 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 커스텀 커넥터 관리자(roles/connectors.customConnectorAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

커스텀 커넥터 만들기

백엔드 연결 시나리오에 설명된 대로 커스텀 커넥터는 다음과 같은 연결 패턴을 가질 수 있습니다.

백엔드의 공개 엔드포인트에 직접 연결
중간 공개 엔드포인트를 통해 백엔드에 간접 연결

이러한 두 가지 패턴에서 커스텀 커넥터 만들기 단계에 약간의 차이점이 있습니다.

직접 연결로 만들기

백엔드의 엔드포인트에 직접 연결되는 커스텀 커넥터를 만들려면 다음 단계를 따르세요.

콘솔

콘솔에서 Integration Connectors > 커스텀 커넥터 페이지로 이동한 후 Google Cloud 프로젝트를 선택하거나 만듭니다.
커스텀 커넥터 페이지로 이동
새로 만들기를 클릭하여 커스텀 커넥터 만들기 페이지를 엽니다.
커넥터 세부정보 섹션에서 다음 필드를 설정합니다.
1. 커넥터 이름: 커넥터 이름을 입력합니다.
2. 표시 이름: 커넥터의 표시 이름을 입력합니다.
3. 설명: 설명을 입력합니다.
4. 서비스 계정: 필수 역할이 있는 서비스 계정을 선택합니다.
5. 로고: 이미지를 커넥터 로고로 사용하려면 Cloud Storage 버킷에 이미지를 업로드합니다.
  참고: Cloud Storage 버킷에 공개 액세스 방지가 사용 중지되어 있는지 확인합니다.
다음을 클릭합니다.
커넥터 사양 섹션에서 다음 필드를 설정합니다.
1. 커스텀 커넥터 유형: 커스텀 커넥터 유형을 선택합니다.
2. 커넥터 사양: Open API 사양의 공개 URL을 입력하거나 사양 파일을 Cloud Storage 버킷에 업로드합니다.
커넥터 구성 세부정보를 검토한 다음 만들기를 클릭합니다.

커넥터가 성공적으로 생성되면 커스텀 커넥터 페이지로 이동에 새로 생성된 커넥터가 표시되며 새 커넥터인 경우, 커넥터의 첫 번째 버전도 생성됩니다. 커스텀 커넥터 세부정보 페이지의 버전 탭에서 버전 세부정보를 확인할 수 있습니다. 자세한 내용은 을 참조하세요.

하지만 백엔드에 연결하려면 새로 만든 커넥터에 대한 연결을 만들어야 합니다. 자세한 내용은 커스텀 커넥터 연결 만들기를 참조하세요.

API

다음 샘플 명령어는 Integration Connectors API를 사용하여 커스텀 커넥터를 만드는 방법을 보여줍니다.

커넥터를 만듭니다.

curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

다음을 바꿉니다.

CUSTOM_CONNECTOR_NAME: 커스텀 커넥터의 이름입니다.
PROJECT_ID: Google Cloud 프로젝트의 ID
UNIQUE_IDENTIFIER: 커넥터의 고유 식별자입니다. 예를 들면 custom-connector-1입니다.

커스텀 커넥터 버전을 구성합니다.

curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL",}' \
"https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"

다음을 바꿉니다.

SPECIFICATION_URL: Open API 사양 URL입니다. 예를 들면 https://petstore3.swagger.io/api/v3/openapi.json입니다.
PROJECT_ID: Google Cloud 프로젝트의 ID
VERSION_NUMBER: 커넥터의 버전 번호입니다. 예를 들면 2입니다.

간접 연결로 만들기

중간 엔드포인트를 통해 백엔드에 연결하는 커스텀 커넥터를 만들려면 다음 단계를 따르세요.

콘솔

콘솔에서 Integration Connectors > 커스텀 커넥터 페이지로 이동한 후 Google Cloud 프로젝트를 선택하거나 만듭니다.
커스텀 커넥터 페이지로 이동
새로 만들기를 클릭하여 커스텀 커넥터 만들기 페이지를 엽니다.
연결 세부정보 섹션에서 다음 필드를 설정합니다.
1. 커넥터 이름: 커넥터 이름을 입력합니다.
2. 표시 이름: 커넥터의 표시 이름을 입력합니다.
3. 설명: 설명을 입력합니다.
4. 백엔드 액세스용 커넥터 대상 구성: 이 옵션을 사용 설정합니다. 그러면 페이지의 추가 구성 섹션이 표시됩니다.
5. 서비스 계정: 필수 역할이 있는 서비스 계정을 선택합니다.
6. 로고: 이미지를 커넥터 로고로 사용하려면 Cloud Storage 버킷에 이미지를 업로드합니다.
  참고: Cloud Storage 버킷에 공개 액세스 방지가 사용 중지되어 있는지 확인합니다.
다음을 클릭합니다.
커넥터 사양 섹션에서 다음 필드를 설정합니다.
1. 커스텀 커넥터 유형: 커스텀 커넥터 유형을 선택합니다.
2. 커넥터 사양: Open API 사양의 공개 URL을 입력하거나 사양 파일을 Cloud Storage 버킷에 업로드합니다.
다음을 클릭합니다.
커넥터 대상 섹션에서 다음 필드를 설정합니다.
1. 대상 유형: 호스트 주소를 선택합니다.
2. 호스트: 중개 서비스가 실행되는 호스트 이름을 입력합니다.
3. 포트: 중개 서비스의 포트 번호를 입력합니다.
다음을 클릭합니다.
커넥터 인증 섹션에서 중개 서비스의 인증 유형을 선택한 후 표시되는 메시지에 따라 해당 세부정보를 입력합니다. 이 단계에서는 Integration Connectors에서 중개 서비스로의 인증을 구성합니다.
중개 서비스에서 백엔드로의 인증은 Integration Connectors에서 구성할 수 없으며, 백엔드에 인증하는 방법은 중개 서비스에 달려 있습니다.
다음을 클릭합니다.
백엔드 변수 섹션에서 중개 서비스를 통해 백엔드로 전송할 값을 입력합니다. 값을 키-값 쌍으로 구성해야 합니다. 키-값 쌍을 입력하려면 변수 추가를 클릭한 후 다음 필드를 설정합니다.
- 키: 키 이름을 입력합니다.
- 값 유형: 변수의 데이터 유형을 선택합니다.
- 표시 이름: 표시 이름을 입력합니다.
- 위치: 커넥터가 중개 서비스로 변수를 전송하는 방법을 지정합니다. 사용 가능한 옵션은 Header, Request payload, Query parameter입니다.
- 필요한 경우 Required를 선택하여 변수가 필수 변수임을 지정합니다.
참고: 연결을 만들 때 구성한 변수의 값을 입력하라는 메시지가 표시됩니다.
다음을 클릭합니다.
커넥터 구성 세부정보를 검토한 다음 만들기를 클릭합니다.

커넥터가 성공적으로 생성되면 커스텀 커넥터 페이지에 새로 생성된 커넥터가 표시되며 새 커넥터인 경우, 커넥터의 첫 번째 버전도 생성됩니다. 커스텀 커넥터 세부정보 페이지의 버전 탭에서 버전 세부정보를 확인할 수 있습니다. 커스텀 커넥터 버전을 생성하고 수정하는 자세한 내용은 커스텀 커넥터 버전 관리를 참조하세요.

하지만 백엔드에 연결하려면 새로 만든 커넥터에 대한 연결을 만들어야 합니다. 자세한 내용은 커스텀 커넥터 연결 만들기를 참조하세요.

API

다음 샘플 명령어는 Integration Connectors API를 사용하여 커스텀 커넥터를 만드는 방법을 보여줍니다.

커넥터를 만듭니다.

curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

다음을 바꿉니다.

CUSTOM_CONNECTOR_NAME: 커스텀 커넥터의 이름입니다.
PROJECT_ID: Google Cloud 프로젝트의 ID
UNIQUE_IDENTIFIER: 커넥터의 고유 식별자입니다. 예를 들면 custom-connector-1입니다.

커스텀 커넥터 버전 및 인증을 구성합니다.

curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL", \
"service_account":"test-sa", \
"enable_backend_destination_config": true, \
"auth_config": { \
"auth_type":"USER_PASSWORD", \
"auth_key": "basic", \
"user_password": { \
"username":"USERNAME", \
"password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
}}, \
"backend_variable_templates": [{ \
"key":"authkey", \
"value_type":"SECRET", \
"display_name":"Authorization Key", \
"required":true, \
"location_type": "HEADER" \
}], \
"destination_configs":[{ \
"key":"base_url", \
"destinations": [{ \
"host":"DESTINATION_HOST_ADDRESS" \
}]} \
]}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"

다음을 바꿉니다.

SPECIFICATION_URL: Open API 사양 URL입니다. 예를 들면 https://petstore3.swagger.io/api/v3/openapi.json입니다.
PROJECT_ID: Google Cloud 프로젝트의 ID
USERNAME: 중개 서비스 인증을 위한 사용자 이름입니다.
SECRET_VERSION_NUMBER: Secret Manager 보안 비밀 버전 번호입니다. 예를 들면 2입니다.
DESTINATION_HOST_ADDRESS: 중개 서비스의 호스트 주소입니다. 예를 들면 http://www.test.com:80입니다.
CONNECTOR_VERSION_NUMBER: 커스텀 커넥터 버전 번호입니다. 예를 들면 1입니다.

참고: 이 샘플 API 호출은 Username and Password 인증을 사용합니다. 요구사항에 따라 다른 인증 유형을 사용할 수 있습니다.

커스텀 커넥터 연결 만들기

커스텀 커넥터를 만든 후 백엔드에 연결하려면 커스텀 커넥터 유형의 연결을 만들어야 합니다. 새 연결을 만드는 단계는 대략적으로 다음과 같습니다.

Cloud 콘솔에서 Integration Connectors > 연결 페이지로 이동한 다음 Google Cloud 프로젝트를 선택하거나 만듭니다.
연결 페이지로 이동
새로 만들기를 클릭하여 연결 만들기 페이지를 엽니다.
위치 섹션의 리전 필드에서 연결 위치를 선택합니다.
지원되는 모든 리전 목록은 위치를 참조하세요.
다음을 클릭합니다.
연결 세부정보 섹션에서 다음 필드를 설정합니다.
1. 커넥터: 사용 가능한 커넥터의 드롭다운 목록에서 커스텀 커넥터를 선택합니다.
2. 커넥터 버전: 사용 가능한 버전의 드롭다운 목록에서 커넥터 버전을 선택합니다.
3. 연결 이름 필드에서 연결의 이름을 입력합니다.
  연결 이름은 다음 기준을 충족해야 합니다.
  - 연결 이름에 문자, 숫자, 하이픈을 사용할 수 있습니다.
  - 문자는 소문자여야 합니다.
  - 연결 이름은 문자로 시작하고 문자 또는 숫자로 끝나야 합니다.
  - 연결 이름은 63자를 초과할 수 없습니다.
4. 선택적으로 연결에 대한 설명을 입력합니다.
5. 선택적으로 Cloud Logging 사용 설정을 선택하여 Cloud Logging을 사용 설정합니다.
6. 서비스 계정: 필수 역할이 있는 서비스 계정을 선택합니다.
7. 필요한 경우 연결 노드 설정을 구성합니다.
  - 최소 노드 수: 최소 연결 노드 수를 입력합니다.
  - 최대 노드 수: 최대 연결 노드 수를 입력합니다.
  노드는 트랜잭션을 처리하는 연결의 단위(또는 복제본)입니다. 연결에 대해 더 많은 트랜잭션을 처리하려면 더 많은 노드가 필요합니다. 이와 반대로 더 적은 트랜잭션을 처리하기 위해서는 더 적은 노드가 필요합니다. 노드가 커넥터 가격 책정에 미치는 영향을 파악하려면 연결 노드 가격 책정을 참조하세요. 값을 입력하지 않으면 기본적으로 최소 노드가 (높은 가용성을 위해) 2로 설정되고 최대 노드는 50으로 설정됩니다.
8. 선택적으로 라벨 추가를 클릭하여 키-값 쌍의 형식으로 연결에 라벨을 추가합니다.
다음을 클릭합니다.
인증 섹션에서 백엔드의 인증 세부정보를 입력합니다.
- 백엔드에 직접 연결하면 Integration Connectors에서 백엔드 인증을 구성하라는 메시지가 표시됩니다.
- 중개 서비스를 통해 백엔드에 간접적으로 연결하는 경우 Integration Connectors에서 인증 세부정보를 구성하라는 메시지를 표시하지 않습니다. 커넥터를 만들 때는 Integration Connectors과 중개 서비스 간의 인증이 이미 구성된 상태입니다. Integration Connectors는 중개 서비스와 백엔드 간의 인증을 구성하도록 요청하지 않으며, 백엔드에 인증하는 방법은 중개 서비스에 달려 있습니다.
다음을 클릭합니다.
연결 구성 세부정보를 검토한 다음 만들기를 클릭합니다.

연결이 성공적으로 생성되면 모든 연결 페이지에 나열되고 Application Integration에서 연결을 사용할 수 있게 됩니다. 커넥터 태스크를 통해 통합에서 연결을 사용할 수 있습니다.

고려사항

커스텀 커넥터를 만들 때는 다음 사항을 고려하세요.

Integration Connectors는 OpenAPI 버전 3.0과 해당 버전의 모든 부 버전만 지원합니다.
커스텀 커넥터를 만드는 중에는 Open API 사양이 검증되지 않습니다. 커스텀 커넥터의 연결을 만들면 Integration Connectors에서 사양의 유효성을 검사하며 오류가 있으면 연결이 Error 상태가 됩니다.
Integration Connectors는 항목과 작업을 구분하지 않습니다. 따라서 백엔드의 항목과 작업이 커스텀 커넥터에 모두 Actions로 나열됩니다.
VPC 서비스 제어가 사용 설정된 Google Cloud 프로젝트에서는 커스텀 커넥터가 지원되지 않습니다.
Open API 사양 엔드포인트와 백엔드 엔드포인트 모두 공개적으로 액세스가 가능해야 합니다. 즉, 백엔드에 비공개 연결을 설정할 수 없습니다.
멀티파트 미디어 유형은 Open API 사양에서 지원되지 않습니다.
커스텀 커넥터의 버전 세부정보는 수정할 수 없습니다.