검색의 게재 컨트롤 구성

서빙 컨트롤 (컨트롤이라고도 함)은 결과가 반환될 때 요청이 처리되는 기본 동작을 변경합니다. 제공 컨트롤은 데이터 스토어 수준에서 작동합니다.

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

이 페이지에서는 검색 앱의 서빙 컨트롤을 설명합니다. 미디어 추천과 함께 서빙 컨트롤을 사용하는 방법에 대한 자세한 내용은 미디어 서빙 구성 만들기 및 관리를 참고하세요.

서빙 컨트롤 정보

요청 결과를 변경하려면 먼저 서빙 컨트롤을 만듭니다. 그런 다음 해당 컨트롤을 검색 앱의 서빙 구성에 연결합니다. 서빙 구성은 검색 결과 또는 답변과 같은 서빙 시간 결과를 생성하는 데 사용되는 메타데이터를 구성합니다. 서빙 컨트롤은 컨트롤이 앱의 서빙 구성에 연결된 경우에만 앱에서 제공하는 요청에 영향을 미칩니다.

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

서빙 컨트롤 유형

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

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

조건 정보

컨트롤을 만들 때 컨트롤이 적용되는 시점을 결정하는 조건을 선택적으로 정의할 수 있습니다. 조건은 조건 필드를 사용하여 정의됩니다. 사용 가능한 조건 필드는 다음과 같습니다.

• 검색어 (queryTerms). 특정 쿼리를 검색할 때 적용되는 선택적 컨트롤입니다. queryTerms 조건이 사용되면 queryTerms 값이 SearchRequest.query의 검색어와 일치할 때 컨트롤이 적용됩니다. 쿼리 용어는 Control.searchUseCase가 SOLUTION_TYPE_SEARCH로 설정된 경우에만 사용할 수 있습니다. 단일 Control.condition에 최대 10개의 서로 다른 queryTerms를 지정할 수 있습니다. 검색어가 지정되지 않으면 queryTerms 필드가 무시됩니다.

  프로모션 서빙 컨트롤의 경우 기본 웹사이트 검색에만 적용되는 queryRegex 조건을 지정하는 경우 queryTerms를 지정할 수 없습니다. 또한 기본 웹사이트 검색의 fullMatch 필드는 queryTerms가 지정된 경우 true로 설정해야 합니다. 다른 모든 검색 앱의 경우 queryTerms만 지원되며 fullMatch은 true 또는 false로 설정할 수 있습니다.

• 기간 (activeTimeRange). 지정된 기간 내에 요청이 발생할 때 적용되는 선택적 컨트롤입니다. 요청이 수신된 시간이 activeTimeRange.startTime와 activeTimeRange.endTime 사이인지 확인합니다. 단일 Control.condition에서 최대 10개의 activeTimeRange 범위를 지정할 수 있습니다. activeTimeRange 필드가 지정되지 않으면 필드가 무시됩니다.

• queryRegex. 기본 웹사이트 검색의 프로모션 게재 관리에만 사용할 수 있습니다. 이는 쿼리가 지정된 정규 표현식과 일치할 때 컨트롤을 적용하는 선택적 조건입니다. queryTerms 조건을 지정하는 경우 이 조건을 지정할 수 없습니다.

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

예를 들어 쿼리 용어가 두 개 지정된 다음 조건을 고려해 보세요.

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

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

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

자세한 내용은 API 참조에서 Condition 필드를 참고하세요.

부스트 서빙 컨트롤 만들기 및 연결

부스트 서빙 컨트롤은 적용된 조건에 따라 결과를 승격하거나 강등하여 순서를 재정렬합니다. 부스트는 부스트 조건을 충족하는 문서의 순위에 곱셈 인자를 적용하여 작동합니다.

부스트 컨트롤을 만들고 연결하려면 다음을 수행하세요.

콘솔

1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

   AI 애플리케이션

2. 부스트 컨트롤을 만들 앱을 선택합니다.

3. 앱의 개요 페이지에서 신호 단계에 나열된 강조/숨기기를 선택합니다.

4. 신호 페이지에서 컨트롤 만들기를 클릭합니다.

5. 제어 만들기 창에서 다음을 수행합니다.

   1. 강조/숨김 컨트롤의 이름을 입력하고 계속을 클릭합니다.

   2. 컨트롤을 트리거하는 다음 조건을 설정합니다. 조건이 구성되지 않으면 컨트롤이 항상 적용됩니다.

      1. 부분 일치 검색어를 추가합니다. 이러한 쿼리 검색어가 부분적으로 일치하면 컨트롤이 적용됩니다.

      2. 완전 일치 검색어를 추가합니다. 이러한 쿼리 용어가 정확히 일치하면 컨트롤이 적용됩니다.

      3. 활성 시간 범위를 추가하려면 시간 범위 추가를 클릭하고 시작 시간 1과 종료 시간 1을 설정합니다. 이 값은 조건이 활성 상태인 기간을 정의합니다. 시간 범위는 최대 10개까지 추가할 수 있습니다.

      4. 계속을 클릭합니다.

   3. 이 컨트롤로 트리거할 작업을 정의합니다.

      1. 목록에서 데이터 스토어를 선택합니다. 작업을 여러 데이터 스토어에 적용하려면 데이터 스토어마다 컨트롤을 만듭니다.

      2. 필터를 추가합니다.

         문서에서 충족해야 하는 요구사항을 지정하는 문자열입니다. 문서가 모든 요구사항과 일치하는 경우에만 부스트 조건이 적용됩니다. 그렇지 않으면 변경사항이 없습니다. 필터를 지정하지 않으면 데이터 스토어의 모든 문서에 부스트가 적용됩니다.

         필터 표현식을 작성하는 방법을 알아보려면 필터 표현식 문법 및 필터 표현식 예를 참고하세요.

      3. 슬라이더를 사용하여 [-1, 1] 범위에서 부스트/하강 값을 선택합니다. 슬라이더는 0.01 단위로 이동합니다.

      4. 계속을 클릭합니다.

   4. 컨트롤을 생성하는 즉시 적용하려면 이 컨트롤을 즉시 게시를 사용 설정하고 계속을 클릭합니다.

6. 제출을 클릭합니다.

7. 컨트롤의 구성을 수정하려면 다음을 수행합니다.

   1. 신호 페이지의 앱 부스트/묻기 컨트롤 목록에서 수정할 컨트롤의 을 클릭하고 수정을 클릭합니다.

   2. 컨트롤 수정 창에서 컨트롤을 수정합니다.

8. 컨트롤을 사용 설정 또는 사용 중지하려면 신호 페이지의 앱 부스트/묻기 컨트롤 목록에서 사용 설정 또는 사용 중지하려는 컨트롤의 아이콘을 클릭하고 각각 사용 설정 또는 사용 중지를 클릭합니다.

9. 컨트롤을 삭제하려면 신호 페이지의 앱 부스트/매장 컨트롤 목록에서 삭제하려는 컨트롤의 를 클릭하고 삭제를 클릭합니다.

REST

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

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

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

1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

   1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

   2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

2. 다음 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/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": [
     "USE_CASE"
   ],
   "conditions": {
    "queryTerms": [
      {
        "value": "VALUE",
        "fullMatch": FULL_MATCH
      }
    ],
    "activeTimeRange": [
      {
        "startTime": "START_TIMESTAMP",
        "endTime": "END_TIMESTAMP"
      }
    ]
   },
   "boostAction": {
     "boost": BOOST_VALUE,
     "filter": "FILTER",
     "dataStore": "DATA_STORE_RESOURCE_PATH"
    }
   }'

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 번호 또는 ID입니다.
   • APP_ID: Vertex AI Search 앱의 ID입니다.
   • CONTROL_ID: 컨트롤의 고유 식별자입니다. ID에는 문자, 숫자, 하이픈, 밑줄이 될 수 있는 [1~63] 개의 문자가 포함될 수 있습니다.
   • DISPLAY_NAME: 사람이 읽을 수 있는 컨트롤 이름입니다. 이 이름을 통해 컨트롤을 사용해야 하는 경우나 이유에 대한 정보를 제공하는 것이 좋습니다. 길이가 [1,128]인 UTF-8로 인코딩된 문자열이어야 합니다.
   • USE_CASE: SEARCH_USE_CASE_SEARCH 또는 SEARCH_USE_CASE_BROWSE 중 하나여야 합니다. SEARCH_USE_CASE_BROWSE가 지정된 경우 Condition.queryTerms을 조건에서 사용할 수 없습니다.
   • CONDITION: 컨트롤을 적용해야 하는 시기를 정의하는 선택적 필드입니다. 다음 필드가 포함됩니다.
     • VALUE: 일치시킬 특정 쿼리 값입니다. 길이가 [1, 5000]인 소문자 UTF-8 문자열입니다. FULL_MATCH_1이 true이면 이 필드에는 공백으로 구분된 최대 3개의 용어가 있을 수 있습니다.
     • FULL_MATCH: 검색어가 검색어와 정확히 일치해야 하는지 여부를 나타내는 불리언입니다. true로 설정된 경우 SearchRequest.query이 queryTerm.value와 완전히 일치해야 합니다. false로 설정하면 SearchRequest.query에 queryTerm.value이 하위 문자열로 포함되어야 합니다.
     • START_TIMESTAMP: 시간 범위의 시작을 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
     • END_TIMESTAMP: 기간의 종료를 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
   • BOOST_VALUE: [-1,1] 범위의 부동 소수점 숫자입니다. 값이 음수이면 결과가 강등되어 결과 하단에 표시됩니다. 값이 양수이면 결과가 승격하여 결과 상단에 표시됩니다. 자세한 내용은 boostAction를 참조하세요.
   • FILTER: 문서에서 충족해야 하는 요구사항을 지정하는 문자열입니다. 문서가 모든 요구사항과 일치하면 부스트가 적용됩니다. 그렇지 않으면 변경사항이 없습니다. 이 필드가 비어 있으면 데이터 스토어의 모든 문서에 부스트가 적용됩니다. 필터링 문법은 필터 표현식 문법을 참고하세요. 참고: 문서 필드 title는 필터링할 수 없습니다.
   • DATA_STORE_RESOURCE_PATH: 이 컨트롤로 문서가 부스팅되어야 하는 데이터 스토어의 전체 리소스 경로입니다. 전체 리소스 경로의 형식은 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID입니다. 이 데이터 스토어는 요청에서 지정된 엔진에 연결되어야 합니다.

3. engines.servingConfigs.patch 메서드를 사용하여 컨트롤을 앱의 서빙 구성에 연결합니다.

   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/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
   -d '{
    "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
   }'

   BOOST_ID_N를 이전 단계에서 만든 컨트롤 ID로 바꿉니다.

필터 서빙 컨트롤 만들기 및 연결

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

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

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

1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

   1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

   2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

2. 다음 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/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": FULL_MATCH
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ]
   },
   "filterAction": {
     "filter": "FILTER"
    }
   }'

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 번호 또는 ID입니다.
   • APP_ID: Vertex AI Search 앱의 ID입니다.
   • CONTROL_ID: 컨트롤의 고유 식별자입니다. ID에는 문자, 숫자, 하이픈, 밑줄이 될 수 있는 [1~63] 개의 문자가 포함될 수 있습니다.
   • DISPLAY_NAME: 사람이 읽을 수 있는 컨트롤 이름입니다. 이 이름을 통해 컨트롤을 사용해야 하는 경우나 이유에 대한 정보를 제공하는 것이 좋습니다. 길이가 [1,128]인 UTF-8로 인코딩된 문자열이어야 합니다.
   • USE_CASE: SEARCH_USE_CASE_SEARCH 또는 SEARCH_USE_CASE_BROWSE 중 하나여야 합니다. SEARCH_USE_CASE_BROWSE가 지정된 경우 Condition.queryTerms을 조건에서 사용할 수 없습니다.
   • CONDITION: 컨트롤을 적용해야 하는 시기를 정의하는 선택적 필드입니다. 다음 필드가 포함됩니다.
     • VALUE: 일치시킬 특정 쿼리 값입니다. 길이가 [1, 5000]인 소문자 UTF-8 문자열입니다. FULL_MATCH_1이 true이면 이 필드에는 공백으로 구분된 최대 3개의 용어가 있을 수 있습니다.
     • FULL_MATCH: 검색어가 검색어와 정확히 일치해야 하는지 여부를 나타내는 불리언입니다. true로 설정된 경우 SearchRequest.query이 queryTerm.value와 완전히 일치해야 합니다. false로 설정하면 SearchRequest.query에 queryTerm.value이 하위 문자열로 포함되어야 합니다.
     • START_TIMESTAMP: 시간 범위의 시작을 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
     • END_TIMESTAMP: 기간의 종료를 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
   • FILTER: 문서에서 충족해야 하는 요구사항을 지정하는 문자열입니다. 문서가 모든 요구사항과 일치하면 문서가 결과에 반환됩니다. 그렇지 않으면 문서가 결과에 표시되지 않습니다. 필터링 문법은 필터 표현식 문법을 참조하세요. 자세한 내용은 filterAction를 참조하세요. 참고: 문서 필드 title는 필터링할 수 없습니다.

3. engines.servingConfigs.patch 메서드를 사용하여 컨트롤을 앱의 서빙 구성에 연결합니다.

   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/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
   -d '{
     "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
   }'

   FILTER_ID_N를 이전 단계에서 만든 컨트롤 ID로 바꿉니다.

동의어 서빙 컨트롤 만들기 및 연결

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

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

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

1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

   1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

   2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

2. 다음 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/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": FULL_MATCH
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ]
   },
   "synonymsAction": {
     "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
    }
   }'

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 번호 또는 ID입니다.
   • APP_ID: Vertex AI Search 앱의 ID입니다.
   • CONTROL_ID: 컨트롤의 고유 식별자입니다. ID에는 문자, 숫자, 하이픈, 밑줄이 될 수 있는 [1~63] 개의 문자가 포함될 수 있습니다.
   • DISPLAY_NAME: 사람이 읽을 수 있는 컨트롤 이름입니다. 이 이름을 통해 컨트롤을 사용해야 하는 경우나 이유에 대한 정보를 제공하는 것이 좋습니다. 길이가 [1,128]인 UTF-8로 인코딩된 문자열이어야 합니다.
   • USE_CASE: SEARCH_USE_CASE_SEARCH 또는 SEARCH_USE_CASE_BROWSE 중 하나여야 합니다. SEARCH_USE_CASE_BROWSE가 지정된 경우 Condition.queryTerms을 조건에서 사용할 수 없습니다.
   • CONDITION: 컨트롤을 적용해야 하는 시기를 정의하는 선택적 필드입니다. 다음 필드가 포함됩니다.
     • VALUE: 일치시킬 특정 쿼리 값입니다. 길이가 [1, 5000]인 소문자 UTF-8 문자열입니다. FULL_MATCH_1이 true이면 이 필드에는 공백으로 구분된 최대 3개의 용어가 있을 수 있습니다.
     • FULL_MATCH: 검색어가 검색어와 정확히 일치해야 하는지 여부를 나타내는 불리언입니다. true로 설정된 경우 SearchRequest.query이 queryTerm.value와 완전히 일치해야 합니다. false로 설정하면 SearchRequest.query에 queryTerm.value이 하위 문자열로 포함되어야 합니다.
     • START_TIMESTAMP: 시간 범위의 시작을 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
     • END_TIMESTAMP: 기간의 종료를 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
   • SYNONYMS_N: 서로 연결되어 비슷한 결과를 더 많이 보여줄 가능성이 높은 문자열 목록입니다. 동의어 항목을 각각 검색하면 유사한 결과가 표시될 가능성이 높지만, 연결된 모든 동의어에 대한 관련 결과가 모두 표시되지는 않을 수 있습니다. 동의어를 2개 이상 지정해야 하며 최대 100개의 동의어를 지정할 수 있습니다. 각 동의어는 UTF-8로 인코딩되어야 하며 소문자여야 합니다. 중복 문자열은 허용되지 않습니다. 예를 들어 'Pixel', 'Android 휴대전화', 'Google 휴대전화'를 동의어로 추가할 수 있습니다. 자세한 내용은 synonymsAction를 참조하세요.

3. engines.servingConfigs.patch 메서드를 사용하여 컨트롤을 앱의 서빙 구성에 연결합니다.

   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/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
   -d '{
     "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
   }'

   SYNONYMS_ID_N를 이전 단계에서 만든 컨트롤 ID로 바꿉니다.

리디렉션 서빙 컨트롤 만들기 및 연결

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

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

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

1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

   1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

   2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

2. 다음 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/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": FULL_MATCH
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ]
   },
   "redirectAction": {
     "redirectURI": "REDIRECT_URI"
    }
   }'

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 번호 또는 ID입니다.
   • APP_ID: Vertex AI Search 앱의 ID입니다.
   • CONTROL_ID: 컨트롤의 고유 식별자입니다. ID에는 문자, 숫자, 하이픈, 밑줄이 될 수 있는 [1~63] 개의 문자가 포함될 수 있습니다.
   • DISPLAY_NAME: 사람이 읽을 수 있는 컨트롤 이름입니다. 이 이름을 통해 컨트롤을 사용해야 하는 경우나 이유에 대한 정보를 제공하는 것이 좋습니다. 길이가 [1,128]인 UTF-8로 인코딩된 문자열이어야 합니다.
   • USE_CASE: SEARCH_USE_CASE_SEARCH 또는 SEARCH_USE_CASE_BROWSE 중 하나여야 합니다. SEARCH_USE_CASE_BROWSE가 지정된 경우 Condition.queryTerms을 조건에서 사용할 수 없습니다.
   • CONDITION: 컨트롤을 적용해야 하는 시기를 정의하는 선택적 필드입니다. 다음 필드가 포함됩니다.
     • VALUE: 일치시킬 특정 쿼리 값입니다. 길이가 [1, 5000]인 소문자 UTF-8 문자열입니다. FULL_MATCH_1이 true이면 이 필드에는 공백으로 구분된 최대 3개의 용어가 있을 수 있습니다.
     • FULL_MATCH: 검색어가 검색어와 정확히 일치해야 하는지 여부를 나타내는 불리언입니다. true로 설정된 경우 SearchRequest.query이 queryTerm.value와 완전히 일치해야 합니다. false로 설정하면 SearchRequest.query에 queryTerm.value이 하위 문자열로 포함되어야 합니다.
     • START_TIMESTAMP: 시간 범위의 시작을 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
     • END_TIMESTAMP: 기간의 종료를 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
   • REDIRECT_URI_N: 리디렉션되는 URI입니다. 최대 길이는 2,000자(영문 기준)입니다. 예를 들어 검색어 값이 '지원'인 경우 '지원'에 대한 검색 결과를 반환 (또는 반환 실패)하는 대신 기술 지원 페이지로 리디렉션을 설정할 수 있습니다. 이 예에서 리디렉션 URI는 "https://www.example.com/support"가 됩니다. 자세한 내용은 redirectAction를 참조하세요.

3. engines.servingConfigs.patch 메서드를 사용하여 컨트롤을 앱의 서빙 구성에 연결합니다.

   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/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
   -d '{
     "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
   }'

   REDIRECT_ID_N를 이전 단계에서 만든 컨트롤 ID로 바꿉니다.

프로모션 서빙 컨트롤 만들기 및 연결

프로모션 서빙 컨트롤을 사용하면 링크를 프로모션 결과로 표시할 수 있으며, 다음 유형의 검색 데이터 스토어에서 사용할 수 있습니다.

• 기본 웹사이트 검색이 있는 웹사이트 데이터 스토어: 이러한 데이터 스토어의 경우 앱의 제공 구성에 프로모션 관리 기능을 연결할 필요가 없습니다. 프로모션 관리 기능을 만들고 사용 설정하면 프로모션 관리 기능이 활성화됩니다. 사용 설정 또는 사용 중지하여 프로모션 컨트롤을 사용 설정하거나 사용 중지할 수 있습니다.

• 정형 및 비정형 데이터가 있는 데이터 스토어, 고급 웹사이트 색인 생성이 있는 웹사이트 데이터, 혼합 검색 앱: 이러한 데이터 스토어의 경우 프로모션 컨트롤을 제공 구성에 연결해야 합니다.

프로모션 컨트롤은 promoteAction을 사용하여 정의됩니다.

프로모션 컨트롤을 성공적으로 만들려면 생성 요청에 다음 필드 중 하나가 필요합니다.

• queryTerms: 기본 웹사이트 검색에만 적용되는 queryRegex 조건을 지정하는 경우 이 조건을 지정할 수 없습니다. 기본 웹사이트 검색의 경우 queryTerms가 지정된 경우 fullMatch을 true로 설정해야 합니다. 다른 모든 검색 앱의 경우 queryTerms만 지원되며 fullMatch은 true 또는 false로 설정할 수 있습니다.
• queryRegex. 기본 웹사이트 검색의 프로모션 게재 관리에만 사용할 수 있습니다. 이 조건은 쿼리가 지정된 정규 표현식과 일치할 때 컨트롤을 적용합니다. queryTerms 조건을 지정하는 경우 이 조건을 지정할 수 없습니다.

즉, 기본 웹사이트 검색의 경우 fullMatch이 true로 설정된 queryTerms 필드를 지정하거나 queryRegex 필드를 지정해야 합니다. 다른 모든 유형의 검색의 경우 fullMatch이 true 또는 false로 설정된 queryTerms 필드를 지정합니다.

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

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

1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

   1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

   2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

2. 다음 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/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": true
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ],
     "queryRegex": "VALUE_REGEX"
   },
   "promoteAction": {
     "dataStore": "DATA_STORE_RESOURCE_PATH",
     "searchLinkPromotion": {
        "document": "DOCUMENT_RESOURCE_PATH",
        "title": "TITLE",
        "uri": "URI",
        "description": "DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE,
     }
    }
   }'

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 번호 또는 ID입니다.
   • APP_ID: Vertex AI Search 앱의 ID입니다.
   • CONTROL_ID: 컨트롤의 고유 식별자입니다. ID에는 문자, 숫자, 하이픈, 밑줄이 될 수 있는 [1~63] 개의 문자가 포함될 수 있습니다.
   • DISPLAY_NAME: 사람이 읽을 수 있는 컨트롤 이름입니다. 이 이름을 통해 컨트롤을 사용해야 하는 경우나 이유에 대한 정보를 제공하는 것이 좋습니다. 길이가 [1,128]인 UTF-8로 인코딩된 문자열이어야 합니다.
   • USE_CASE: SEARCH_USE_CASE_SEARCH 또는 SEARCH_USE_CASE_BROWSE 중 하나여야 합니다. SEARCH_USE_CASE_BROWSE가 지정된 경우 Condition.queryTerms을 조건에서 사용할 수 없습니다.
   • Condition: 컨트롤을 적용해야 하는 시기를 정의하는 선택적 객체입니다. 다음 필드가 포함됩니다.
     • queryTerms: queryRegex 필드와 함께 사용할 수 없습니다.
       • VALUE: 일치시킬 특정 쿼리 값입니다. 길이가 [1, 5000]인 소문자 UTF-8 문자열입니다.
     • activeTimeRange:
       • START_TIMESTAMP: 시간 범위의 시작을 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
       • END_TIMESTAMP: 기간의 종료를 나타내는 RFC 3339 UTC 'Zulu' 형식의 타임스탬프입니다.
     • queryRegex: 기본 웹사이트 검색이 있는 데이터 스토어에서만 사용할 수 있습니다. 이 필드는 queryTerms 필드와 함께 사용할 수 없습니다.
       • VALUE_REGEX: 쿼리와 일치하는 정규 표현식입니다.
   • DATA_STORE_RESOURCE_PATH: 검색 결과에 프로모션 URL이 포함된 데이터 스토어의 전체 리소스 경로입니다. 전체 리소스 경로의 형식은 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID입니다. 이 데이터 스토어는 요청에서 지정된 엔진에 연결되어야 합니다.
   • DOCUMENT_RESOURCE_PATH: 프로모션할 문서의 문서 리소스 경로를 지정하는 필드입니다.
     • 정형 및 비정형 데이터가 있는 검색 데이터 스토어의 경우 DOCUMENT_RESOURCE_PATH 필드의 문서 리소스 경로, URI 필드의 URI 또는 둘 다를 제공해야 합니다. 전체 리소스 경로의 형식은 projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID입니다.
     • 웹사이트 데이터 스토어의 경우 이 필드를 설정 해제하고 대신 URI 필드를 설정해야 합니다.
   • TITLE: 홍보할 문서 또는 웹페이지의 제목을 지정하는 필수 필드입니다. 이 제목은 검색 결과에 표시됩니다.
   • URI: 검색 결과가 사용자를 안내하는 URI 링크를 지정하는 필수 필드입니다. 이 URI는 데이터 스토어에 포함되지 않아도 됩니다.
     • 정형 및 비정형 데이터가 있는 검색 데이터 스토어의 경우 DOCUMENT_RESOURCE_PATH 필드의 문서 리소스 경로, URI 필드의 URI 또는 둘 다를 제공해야 합니다.
     • 웹사이트 데이터 스토어의 경우 필수 필드이므로 설정해야 합니다.
   • DESCRIPTION: 홍보할 문서 또는 웹페이지를 설명하는 선택적 필드로, 검색 결과에 표시됩니다.
   • ENABLED_TRUE|FALSE: 프로모션 컨트롤이 사용 설정되어 앱에 연결되어 있는지 나타내는 선택적 불리언 필드입니다. 이 필드는 기본 웹사이트 검색만 있는 웹사이트 데이터 스토어에 적용됩니다. 이 필드를 false로 설정하면 프로모션 게재 컨트롤이 사용 중지되고 컨트롤이 적용되려면 다음 단계에 설명된 대로 컨트롤을 사용 설정하여 업데이트해야 합니다. 자세한 내용은 promoteAction를 참조하세요.

   응답

   다음과 비슷한 JSON 응답이 표시됩니다.

   {
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
    "displayName": "PROMOTE_CONTROL_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "conditions": [
      {
        "queryTerms": [
          {
            "value": "VALUE",
            "fullMatch": true
          }
        ]
      }
    ],
    "useCases": [
      "SEARCH_USE_CASE_SEARCH"
    ],
    "promoteAction": {
      "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
      "searchLinkPromotion": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE
     }
    }
   }
   

3. 기본 웹사이트 검색을 제외한 모든 검색 앱의 경우 engines.servingConfigs.patch 메서드를 사용하여 컨트롤을 앱의 서빙 구성에 연결합니다. 다음 요청에서 promoteControlIds가 첨부되는 순서는 프로모션 결과가 반환되는 순서입니다.

   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/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
   -d '{
     "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
   }'

   PROMOTE_ID_N를 이전 단계에서 만든 컨트롤 ID로 바꿉니다.

4. 선택사항: 기본 웹사이트 검색의 경우 컨트롤을 앱의 서빙 구성에 연결하지 않아도 됩니다. 하지만 기본 웹사이트 검색의 경우 컨트롤이 생성된 후 컨트롤을 사용 설정 또는 중지하고 engines.control.patch 메서드를 호출할 수 있습니다.

   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/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
   -d '{
   "promoteAction": {
     "searchLinkPromotion": {
        "enabled": ENABLED_TRUE|FALSE,
     }
   }
   }'

예

프로모션 컨트롤에 지정된 쿼리 또는 쿼리 정규 표현식과 일치하는 쿼리를 사용하여 앱에 검색 요청을 보내면 프로모션 링크가 응답에 표시됩니다.

예를 들어 기본 웹사이트 검색이 있는 데이터 스토어에서 다음 구성으로 프로모션 컨트롤을 만든다고 가정해 보겠습니다.

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

그런 다음 다음 검색 요청을 보냅니다.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

다음 잘린 응답과 비슷한 JSON 응답이 수신됩니다. 응답에는 프로모션 링크가 포함된 searchLinkPromotions 필드가 포함됩니다.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

다음 단계

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