서빙 컨트롤 구성

서빙 컨트롤(컨트롤이라고도 함)은 요청의 기본 동작을 변경합니다.

예를 들어 컨트롤은 결과를 증폭하거나 숨길 수 있으며, 반환된 결과에서 항목을 필터링하거나, 쿼리를 동의어로 서로 연결하거나, 쿼리를 지정된 URI로 리디렉션할 수 있습니다.

서빙 컨트롤 정보

요청 결과를 변경하려면 먼저 서빙 컨트롤을 만듭니다. 그런 다음 해당 컨트롤을 앱에 연결합니다. 컨트롤은 컨트롤이 연결된 앱에서 제공하는 요청에만 영향을 미칩니다. 컨트롤이 앱에 연결되어 있지 않으면 아무런 효과가 없습니다.

부스트 컨트롤과 같은 일부 컨트롤은 데이터 스토어에 종속됩니다. 데이터 스토어가 앱에서 삭제되면 데이터 스토어 종속 컨트롤도 해당 앱에서 삭제되고 비활성화되지만 삭제되지는 않습니다.

컨트롤을 만들 때 원하는 경우 컨트롤이 적용되는 시점을 결정하는 조건을 정의할 수 있습니다. 조건은 조건 필드를 사용하여 정의됩니다. 다음과 같은 조건 필드를 사용할 수 있습니다.

queryTerms. 특정 쿼리를 검색할 때 컨트롤이 적용됩니다.
activeTimeRange. 지정된 기간 내에 요청이 발생하면 컨트롤이 적용됩니다.

컨트롤에 두 유형의 조건이 모두 지정된 경우 두 조건 유형이 모두 충족되면 컨트롤이 검색 요청에 적용됩니다. 동일한 조건에 여러 값이 지정된 경우 해당 조건이 충족되려면 값 중 하나만 일치하면 됩니다.

예를 들어 두 개의 검색어를 지정한 다음과 같은 조건을 생각해 보겠습니다.

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

이 조건은 SearchRequest.query="gShoe"가 포함된 요청 또는 SearchRequest.query="gBoot"가 포함된 요청에 대해 충족되지만 SearchRequest.query="gSandal" 또는 다른 문자열의 경우 충족되지 않습니다.

조건을 지정하지 않으면 컨트롤이 항상 적용됩니다.

자세한 내용은 API 참조에서 servingConfigs.search을 참조하세요.

서빙 컨트롤 유형

다음과 같은 유형의 서빙 컨트롤을 사용할 수 있습니다.

제어	설명	적용 대상
부스트 컨트롤	반환된 결과 순서를 변경합니다.	구조화된 데이터가 포함된 데이터 스토어, 구조화된 데이터가 포함된 웹사이트, 메타데이터가 포함된 비정형 데이터 또는 미디어 데이터와 같이 스키마를 지원하는 데이터 스토어가 있는 검색 앱
필터 컨트롤	반환된 결과에서 항목을 삭제합니다.	구조화된 데이터가 포함된 데이터 스토어, 구조화된 데이터가 포함된 웹사이트, 메타데이터가 포함된 비정형 데이터 또는 미디어 데이터와 같이 스키마를 지원하는 데이터 스토어가 있는 검색 앱
동의어 컨트롤	쿼리를 서로 연결	웹사이트, 정형, 비정형 또는 미디어 데이터 스토어가 있는 검색 앱
리디렉션 제어	지정된 URI로 리디렉션	모든 검색 앱

부스트 서빙 컨트롤 정보

부스트 서빙 컨트롤은 boostAction이 있는 컨트롤로 정의됩니다.

boostAction 문법은 다음과 같습니다.

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}

BOOST: -1과 1 사이의 부동 소수점 수입니다. 값이 음수이면 검색 결과에서 나중에 표시되도록 결과가 강등됩니다. 값이 양수이면 검색 결과에서 더 먼저 표시되도록 결과가 승격됩니다.
FILTER: 문서에서 충족해야 하는 요구사항을 지정하는 문자열입니다. 문서가 모든 요구사항과 일치하면 부스트가 적용됩니다. 그렇지 않으면 변경되지 않습니다. 이 필드가 비어 있으면 데이터 스토어의 모든 문서에 부스트가 적용됩니다. 필터링 문법은 필터 표현식 문법을 참조하세요.
DATA_STORE_RESOURCE_PATH: 이 컨트롤로 문서가 부스트되어야 하는 데이터 스토어의 전체 리소스 경로입니다. 전체 리소스 경로의 형식은 projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID입니다. 이 데이터 스토어는 요청에서 지정된 엔진에 연결되어야 합니다.

필터 서빙 컨트롤 정보

필터 서빙 컨트롤은 filterAction이 있는 컨트롤로 정의됩니다.

filterAction 문법은 다음과 같습니다.

{
    "filter": "FILTER"
}

FILTER: 문서에서 충족해야 하는 요구사항을 지정하는 문자열입니다. 문서가 모든 요구사항을 충족하면 결과가 결과 목록에 포함됩니다. 그렇지 않으면 결과가 결과 목록에서 삭제됩니다. 필터링 문법은 필터 표현식 문법을 참조하세요.

동의어 서빙 컨트롤 정보

동의어 서빙 컨트롤은 synonymsAction이 있는 컨트롤로 정의됩니다.

synonymsAction 문법은 다음과 같습니다.

{
    "synonyms": "SYNONYMS"
}

SYNONYMS: 서로 연결되어 비슷한 결과를 더 많이 보여줄 가능성이 높은 문자열. 문자열을 2개 이상 지정해야 하며 최대 100개까지 지정할 수 있습니다. 문자열은 UTF-8이어야 하며 소문자로 표시해야 합니다. 중복 문자열은 허용되지 않습니다.

예를 들면 다음과 같습니다.

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

리디렉션 서빙 컨트롤 정보

리디렉션 서빙 컨트롤을 사용하면 사용자를 제공된 URI로 리디렉션할 수 있습니다.

리디렉션 컨트롤은 redirectAction이 있는 컨트롤로 정의됩니다.

redirectAction의 문법:

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI: 최대 2,000자 길이의 URI입니다.

예를 들어 검색어 값이 '지원'인 경우 '지원' 검색 결과를 반환하거나 반환하지 않는 대신 기술 지원 페이지로 리디렉션을 설정할 수 있습니다.

{
    "redirect_uri": ["https://www.example.com/support"]
}

`queryTerms` 조건 정보

queryTerms은 선택사항입니다. 특정 쿼리를 검색할 때 서빙 컨트롤을 사용하려면 이 속성을 사용하세요. queryTerms 조건이 사용되면 queryTerms 값이 SearchRequest.query의 검색어와 일치할 때 컨트롤이 적용됩니다.

검색어는 Control.searchUseCase가 SOLUTION_TYPE_SEARCH로 설정된 경우에만 사용할 수 있습니다.

단일 Control.condition에 최대 10개의 서로 다른 queryTerms를 지정할 수 있습니다. 검색어를 지정하지 않으면 필드가 무시됩니다.

단일 queryTerm 문법은 다음과 같습니다.

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}

VALUE_1: 길이가 [1, 5000]인 소문자 UTF-8 문자열입니다. FULL_MATCH_1이 true이면 공백으로 구분된 최대 3개의 용어가 있을 수 있습니다.
FULL_MATCH_1: 불리언. true로 설정하면 SearchRequest.query가 queryTerm.value와 완전히 일치해야 합니다. false로 설정하면 SearchRequest.query에 queryTerm.value가 하위 문자열로 포함되어야 합니다.

`activeTimeRange` 조건 정보

activeTimeRange은 선택사항입니다. 요청이 수신된 시간이 activeTimeRange.startTime과 activeTimeRange.endTime 사이인지 확인합니다.

단일 Control.condition에 최대 10개의 activeTimeRange 범위를 지정할 수 있습니다. activeTimeRange 범위가 지정되지 않으면 필드가 무시됩니다.

단일 activeTimeRange 문법은 다음과 같습니다.

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1: 제어가 적용되는 가장 빠른 시간(해당 값 포함)을 정의합니다. 타임스탬프는 RFC 3339 UTC 'Zulu' 형식으로 나노초 단위이며 소수점 이하 9자리입니다(예: "2023-10-02T15:01:23Z").
END_TIMESTAMP_1: 제어가 적용되는 마지막 시간(해당 값 포함)을 정의합니다. 이 시간은 미래여야 합니다.

API 안내: 서빙 컨트롤로 기본 검색 요청 동작 변경

기본 검색 요청 동작을 변경하려면 서빙 컨트롤을 만들고 기본 서빙 구성에 연결합니다.

시작하기 전에

서빙 컨트롤을 만들려면 Google 계정팀에 문의하여 서빙 컨트롤 허용 목록에 추가해 달라고 요청하세요.

서빙 컨트롤 만들기

다음 안내에 따라 서빙 컨트롤을 만듭니다.

필드 세부정보는 Controls API 참조 및 Controls.create API 참조를 확인하세요.

데이터 스토어 ID를 찾습니다. 데이터 스토어 ID가 이미 있는 경우 다음 단계로 건너뜁니다.
1. Google Cloud 콘솔에서 Agent Builder 페이지로 이동하고 탐색 메뉴에서 데이터 스토어를 클릭합니다.
  
  데이터 스토어 페이지로 이동
2. 데이터 스토어 이름을 클릭합니다.
3. 데이터 스토어의 데이터 페이지에서 데이터 스토어 ID를 가져옵니다.

컨트롤의 조건 유형 및 필드 값을 선택합니다.

다음은 조건의 잘린 예시입니다.

{
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

다음 curl 명령어를 실행하여 컨트롤을 만듭니다.

부스트 컨트롤: 클릭하여 부스트 컨트롤을 만드는 curl 명령어를 확인합니다.

다음 curl 명령어를 실행합니다.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

필터 컨트롤: 클릭하여 필터 컨트롤을 만드는 curl 명령어를 확인합니다.

다음 curl 명령어를 실행합니다.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

동의어 컨트롤: 클릭하여 동의어 컨트롤을 만드는 curl 명령어를 확인합니다.

다음 curl 명령어를 실행합니다.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

리디렉션 컨트롤: 클릭하여 리디렉션 컨트롤을 만드는 curl 명령어를 확인합니다.

다음 curl 명령어를 실행합니다.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'

PROJECT_ID: Google Cloud 프로젝트의 프로젝트 번호 또는 ID입니다.
DATA_STORE_ID: 데이터 스토어의 고유 ID입니다.
CONTROL_ID: 컨트롤의 고유 식별자(데이터 스토어 내)입니다. ID에는 소문자, 숫자, 하이픈, 밑줄을 포함될 수 있습니다.
DISPLAY_NAME: 인간이 읽을 수 있는 컨트롤 이름입니다. 이 이름을 통해 컨트롤을 사용해야 하는 경우나 이유에 대한 정보를 제공하는 것이 좋습니다. 길이가 [1,128]인 UTF-8 문자열이어야 합니다.
USE_CASE: SEARCH_USE_CASE_SEARCH 또는 SEARCH_USE_CASE_BROWSE 중 하나여야 합니다. SEARCH_USE_CASE_BROWSE가 지정된 경우 조건에 Condition.queryTerms를 사용할 수 없습니다.
CONDITION: (선택사항) 컨트롤을 적용해야 하는 시점을 정의합니다.
BOOST_ACTION: 부스트 컨트롤을 정의하는 데 사용됩니다. boostAction API 참조를 확인하세요.
FILTER_ACTION: 필터 컨트롤을 정의하는 데 사용됩니다. filterAction API 참조를 확인하세요.
SYNONYMS_ACTION: 동의어 컨트롤을 정의하는 데 사용됩니다. synonymsAction API 참조를 확인하세요.
REDIRECT_ACTION: 리디렉션 URI를 지정하는 데 사용됩니다. redirectAction API 참조를 확인하세요.

컨트롤을 앱에 연결합니다.

부스트 컨트롤: 부스트 컨트롤의 curl 명령어를 보려면 클릭하세요.

다음 curl 명령어를 실행하여 서빙 요청에 사용 설정하도록 서빙 구성에 부스트 컨트롤을 연결합니다.

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

BOOST_ID_1 및 BOOST_ID_2: 이전 단계에서 만든 컨트롤 ID를 나타냅니다.

필터 컨트롤: 필터 컨트롤의 curl 명령어를 클릭합니다.

다음 curl 명령어를 실행하여 필터 컨트롤을 서빙 구성에 연결하여 서빙 요청에서 사용하도록 설정합니다.

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

FILTER_ID_1 및 FILTER_ID_2: 이전 단계에서 만든 컨트롤 ID를 나타냅니다.

동의어 컨트롤: 동의어 컨트롤의 curl 명령어를 보려면 클릭하세요.

다음 curl 명령어를 실행하여 서빙 요청에서 사용할 수 있도록 앱에 동의어 컨트롤을 연결합니다.

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

SYNONYM_ID_1 및 SYNONYM_ID_2: 이전 단계에서 만든 컨트롤 ID를 나타냅니다.

리디렉션 컨트롤: 리디렉션 컨트롤의 curl 명령어를 보려면 클릭합니다.

다음 curl 명령어를 실행하여 서빙 요청에 사용할 수 있도록 앱에 리디렉션 컨트롤을 연결합니다.

    curl -X PATCH
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

REDIRECT_ID_1 및 REDIRECT_ID_2: 이전 단계에서 만든 컨트롤 ID를 나타냅니다.

다음 단계

서빙 컨트롤이 일반 검색 앱의 검색 품질에 미치는 영향을 파악하려면 검색 품질을 평가하세요. 자세한 내용은 검색 품질 평가를 참조하세요.

서빙 컨트롤 구성

서빙 컨트롤 정보

서빙 컨트롤 유형

부스트 서빙 컨트롤 정보

필터 서빙 컨트롤 정보

동의어 서빙 컨트롤 정보

리디렉션 서빙 컨트롤 정보

queryTerms 조건 정보

activeTimeRange 조건 정보

API 안내: 서빙 컨트롤로 기본 검색 요청 동작 변경

시작하기 전에

서빙 컨트롤 만들기

다음 단계

`queryTerms` 조건 정보

`activeTimeRange` 조건 정보