카탈로그 정보 가져오기

이 페이지에서는 카탈로그 정보를 가져오고 최신 상태로 유지하는 방법을 설명합니다.

이 페이지의 가져오기 절차는 추천 및 검색에 모두 적용됩니다. 데이터를 가져온 후 두 서비스가 모두 이 데이터를 사용할 수 있으므로 두 서비스를 모두 사용하는 경우 동일한 데이터를 두 번 가져올 필요가 없습니다.

BigQuery에서 카탈로그 데이터 가져오기

이 튜토리얼에서는 BigQuery 테이블을 사용하여 제한 없이 대량의 카탈로그 데이터를 가져오는 방법을 보여줍니다.

Cloud Shell 편집기에서 이 태스크의 단계별 안내를 직접 수행하려면 둘러보기를 클릭합니다.

둘러보기

Cloud Storage에서 카탈로그 데이터 가져오기

이 튜토리얼에서는 많은 수의 항목을 카탈로그로 가져오는 방법을 보여줍니다.

Cloud Shell 편집기에서 이 태스크의 단계별 안내를 직접 수행하려면 둘러보기를 클릭합니다.

둘러보기

인라인으로 카탈로그 데이터 가져오기

이 튜토리얼에서는 인라인으로 카탈로그에 제품을 가져오는 방법을 보여줍니다.

Cloud Shell 편집기에서 이 태스크의 단계별 안내를 직접 수행하려면 둘러보기를 클릭합니다.

둘러보기

시작하기 전에

카탈로그 정보를 가져오려면 먼저 시작하기 전에에서도 특히 프로젝트 설정, 서비스 계정 만들기, 로컬 환경에 서비스 계정 추가의 안내를 완료해야 합니다.

가져오기를 수행하려면 Retail 관리자 IAM 역할이 있어야 합니다.

카탈로그 가져오기 권장사항

고품질 결과를 생성하기 위해서는 고품질 데이터가 필요합니다. 데이터에 필드가 없거나 실제 값 대신 자리표시자 값이 있는 경우, 예측 및 검색 결과의 품질이 저하됩니다.

카탈로그 데이터를 가져올 때는 다음 권장사항을 구현해야 합니다.

• 어떠한 제품 또는 제품 그룹이 기본 제품이고 어떤 것이 변형 제품인지 결정할 때 신중하게 생각해야 합니다. 데이터를 업로드하기 전에 제품 수준을 참조하세요.

  데이터를 가져온 후에 제품 수준 구성을 변경하려면 상당한 노력이 필요합니다.

  기본 항목은 검색 결과 또는 추천으로 반환됩니다. 변형 항목은 그렇지 않습니다.

  예를 들어 기본 SKU 그룹이 '브이넥 셔츠'라면 추천 모델은 브이넥 셔츠 1개와 어쩌면 라운드넥 셔츠와 깊은 라운드넥 셔츠를 반환할 수 있습니다. 하지만 변형이 사용되지 않고 각 SKU가 기본 항목인 경우 브이넥 셔츠의 모든 색상/사이즈 조합은 추천 패널에 "갈색 브이넥 셔츠, XL 사이즈", "갈색 브이넥 셔츠, L 사이즈'"부터 "흰색 브이넥 셔츠, M 사이즈", "흰색 브이넥 셔츠, S 사이즈"에 이르기까지 별개의 항목으로 반환됩니다.

  collectionMemberIds[]에 기본 제품 ID와 함께 옵션 ID가 포함되어 있으면 컬렉션을 함께 인식할 수 있습니다. 이렇게 하면 사용자가 세트에서 하나 이상의 제품을 구매했을 수 있는 제품 모음이 사용자 이벤트에 캡처되어 전체 세트가 구매에 기여한 것으로 간주됩니다. 이렇게 하면 향후 관련 검색 시 동일한 사용자에게 지정된 컬렉션의 다른 제품을 게재하는 것이 쉬워집니다. 예를 들어 사용자가 이미 이불 커버를 구매한 후 침대 시트 모음의 다른 제품(예: 일치하는 베개 커버 및 맞춤 시트)이 반품됩니다.

• 제품 항목 가져오기 한도를 준수하세요.

  Cloud Storage에서 일괄적으로 가져오려면 각 파일의 크기가 2GB 이하여야 합니다. 일괄 가져오기 요청 하나당 한 번에 최대 100개의 파일을 포함할 수 있습니다.

  인라인 가져오기의 경우에는 한 번에 5,000개 이하의 제품 항목을 가져오세요.

• 모든 필수 카탈로그 정보가 포함되어 있고 올바른지 확인합니다.

  자리표시자 값을 사용하지 마세요.

• 선택적 카탈로그 정보를 최대한 많이 포함합니다.

• 모든 이벤트는 단일 통화를 사용해야 합니다(특히 Google Cloud 콘솔을 사용해 수익 측정항목을 확인하려는 경우). Vertex AI Search for Retail API는 카탈로그당 여러 통화의 사용을 지원하지 않습니다.

• 카탈로그를 최신 상태로 유지합니다.

  카탈로그를 매일 업데이트하는 것이 좋습니다. 주기적 카탈로그 가져오기를 예약하면 시간이 지남에 따라 모델 품질이 저하되지 않습니다. Search for Retail 콘솔을 사용하여 카탈로그를 가져올 때 자동 반복 가져오기를 예약할 수 있습니다. 또는 Google Cloud Scheduler를 사용하여 가져오기를 자동화할 수 있습니다.

• 아직 가져오지 않은 제품 항목의 사용자 이벤트는 기록하지 않습니다.

• 카탈로그 정보를 가져온 후에 프로젝트의 오류 보고 및 로깅 정보를 검토하세요.

  몇 가지 오류가 발생하는 것이 일반적이지만 오류가 많다면 오류를 검토한 후 오류를 유발한 프로세스 문제를 해결해야 합니다.

카탈로그 데이터 가져오기 정보

판매자 센터, Cloud Storage, BigQuery에서 제품 데이터를 가져오거나 요청에서 데이터를 인라인으로 지정할 수 있습니다. 판매자 센터 연결을 제외하고 이러한 각 절차는 일회성 가져오기로 수행됩니다. 정기적으로 카탈로그 가져오기(이상적으로는 매일)를 예약하여 카탈로그가 최신 상태인지 확인하세요. 카탈로그를 최신 상태로 유지 항목을 참조하세요.

개별 제품 항목을 가져올 수도 있습니다. 자세한 내용은 제품 업로드를 참조하세요.

카탈로그 가져오기 고려사항

이 섹션에서는 카탈로그 데이터의 일괄 가져오기에 사용할 수 있는 메서드, 각 메서드 사용 시기, 일부 제한사항에 대해 설명합니다.

카탈로그 브랜치 영구 삭제

새 카탈로그 데이터를 기존 브랜치로 가져오는 경우 카탈로그 브랜치가 비어 있어야 합니다. 이렇게 하면 브랜치로 가져온 데이터의 무결성이 보장됩니다. 브랜치가 비어 있으면 새 카탈로그 데이터를 가져온 후 브랜치를 판매자 계정에 연결할 수 있습니다.

실시간 예측이나 검색 트래픽을 제공하고 기본 브랜치를 영구 삭제하려면 먼저 삭제하기 전에 다른 브랜치를 기본값으로 지정하는 것이 좋습니다. 기본 브랜치가 삭제된 후 빈 결과를 제공하므로 활성 기본 브랜치를 삭제하면 서비스가 중단될 수 있습니다.

카탈로그 브랜치에서 데이터를 영구 삭제하려면 다음 단계를 완료합니다.

1. Search for Retail 콘솔에서 데이터> 페이지로 이동합니다.
   
   데이터 페이지로 이동

2. 브랜치 이름 필드에서 카탈로그 브랜치를 선택합니다.

3. 브랜치 이름 필드 옆에 있는 점 3개로 된 메뉴에서 브랜치 영구 삭제를 선택합니다.

   브랜치의 모든 데이터는 물론 브랜치용으로 생성된 속성도 삭제된다는 경고 메시지가 표시됩니다.

4. 브랜치를 입력하고 확인을 클릭하여 브랜치에서 카탈로그 데이터를 영구 삭제합니다.

   장기 실행 작업이 시작되어 카탈로그 브랜치에서 데이터가 영구 삭제됩니다. 영구 삭제 작업이 완료되면 삭제 상태가 활동 상태 창의 제품 카탈로그 목록에 표시됩니다.

Vertex AI Search for Retail에 판매자 센터 동기화

판매자 센터와 Vertex AI Search for Retail 사이의 지속적인 동기화를 위해서는 판매자 센터 계정을 Vertex AI Search for Retail에 연결할 수 있습니다. 연결 후에는 판매자 센터 계정의 카탈로그 정보가 Vertex AI Search for Retail로 즉시 전송됩니다.

Vertex AI Search for Retail에 대해 판매자 센터 동기화를 설정할 때는 판매자 센터에 관리자 역할이 할당되어 있어야 합니다. 일반 액세스 역할을 사용하면 UI에서 판매자 센터 피드를 읽을 수 있지만 판매자 센터를 Vertex AI Search for Retail에 동기화하려고 하면 오류 메시지가 표시됩니다. 따라서 판매자 센터를 Vertex AI Search for Retail에 성공적으로 동기화하려면 먼저 역할을 업그레이드해야 합니다.

Vertex AI Search for Retail이 판매자 센터 계정에 연결되어 있으면 동안 판매자 센터의 제품 데이터가 변경되었을 때 이러한 변경사항이 몇 분 내에 Vertex AI Search for Retail에서 자동으로 업데이트됩니다. 판매자 센터 변경사항이 Vertex AI Search for Retail에 동기화되지 않도록 하려면 판매자 센터 계정을 연결 해제하면 됩니다.

판매자 센터 계정을 연결 해제해도 Vertex AI Search for Retail에서 제품이 삭제되지 않습니다. 가져온 제품을 삭제하려면 제품 정보 삭제를 참조하세요.

판매자 센터 계정 동기화

판매자 센터 계정을 동기화하려면 다음 단계를 수행합니다.

연결된 판매자 센터를 보려면 Search for Retail 콘솔 데이터 페이지로 이동하고 페이지 오른쪽 위에서 판매자 센터 버튼을 클릭합니다. 그러면 연결된 판매자 센터 계정 패널이 열립니다. 이 패널에서 추가 판매자 센터 계정을 추가할 수도 있습니다.

가져온 제품을 보는 방법은 카탈로그에 대한 집계된 정보 보기를 참조하세요.

판매자 센터 계정 링크 나열

판매자 센터 계정 링크를 나열합니다.

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

판매자 센터 계정 연결 해제

판매자 센터 계정을 연결 해제하면 해당 계정에서 Vertex AI Search for Retail로의 카탈로그 데이터 동기화가 중지됩니다. 이 절차를 수행해도 이미 업로드된 Vertex AI Search for Retail의 제품은 삭제되지 않습니다.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

판매자 센터 연결 제한사항

• 판매자 센터 계정 한 개를 카탈로그 브랜치 여러 개에 연결할 수 있지만 카탈로그 브랜치 한 개는 판매자 센터 계정 하나에만 연결될 수 있습니다.

• 판매자 센터 계정은 멀티 클라이언트 계정(MCA) 일 수 없습니다. 하지만 개별 하위 계정을 연결할 수 있습니다.

• 판매자 센터 계정을 연결한 후 처음 가져오기를 수행하면 완료하는 데 몇 시간 정도 걸릴 수 있습니다. 소요되는 시간은 판매자 센터 계정의 제품 수에 따라 다릅니다.

• API 메서드를 사용한 제품 수정은 판매자 센터 계정에 연결된 브랜치에 대해 사용 중지됩니다. 이러한 브랜치의 제품 카탈로그 데이터를 변경하려면 판매자 센터를 통해 변경해야 합니다. 그런 후 이러한 변경사항이 Vertex AI Search for Retail에 자동으로 동기화됩니다.

• 판매자 센터 연결을 사용하는 브랜치에서는 컬렉션 제품 유형을 지원하지 않습니다.

• 데이터 정확성을 보장하기 위해 판매자 센터 계정을 빈 카탈로그 브랜치에만 연결할 수 있습니다. 카탈로그 브랜치에서 제품을 삭제하려면 제품 정보 삭제를 참조하세요.

판매자 센터에서 카탈로그 데이터 가져오기

판매자 센터는 매장 및 제품 데이터를 쇼핑 광고 및 기타 Google 서비스에 사용할 수 있게 해주는 도구입니다.

판매자 센터 스키마를 사용하여 BigQuery에서 일회성 절차로 판매자 센터에서 카탈로그 데이터를 일괄 가져올 수 있습니다(추천만 해당).

판매자 센터에서 일괄 가져오기

Search for Retail 콘솔 또는 products.import 메서드를 사용하여 판매자 센터에서 카탈로그 데이터를 가져올 수 있습니다. 일괄 가져오기는 일회성 절차이며 추천의 경우에만 지원됩니다.

판매자 센터에서 카탈로그를 가져오려면 다음 단계를 완료하세요.

1. 판매자 센터 전송의 안내에 따라 판매자 센터에서 BigQuery로의 전송을 설정합니다.

   Google 판매자 센터 제품 테이블 스키마를 사용합니다. 전송이 매일 반복되도록 구성하지만 데이터 세트의 만료 시간은 2일로 구성합니다.

2. BigQuery 데이터 세트가 다른 프로젝트에 있으면 Vertex AI Search for Retail이 BigQuery 데이터 세트에 액세스할 수 있도록 필요한 권한을 구성합니다. 자세히 알아보기

3. BigQuery의 카탈로그 데이터를 Vertex AI Search for Retail로 가져옵니다.

   콘솔

   1. Search for Retail 콘솔에서 데이터> 페이지로 이동합니다.
      
      데이터 페이지로 이동

   2. 가져오기를 클릭하여 가져오기 패널을 엽니다.

   3. 제품 카탈로그를 선택합니다.

   4. 데이터 소스로 BigQuery를 선택합니다.

   5. 카탈로그를 업로드할 브랜치를 선택합니다.

   6. 데이터 스키마로 판매자 센터를 선택합니다.

   7. 데이터가 있는 BigQuery 테이블을 입력합니다.

   8. 선택사항: 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.

      지정하지 않으면 기본 위치가 사용됩니다. 지정하면 BigQuery 및 Cloud Storage 버킷은 같은 리전에 있어야 합니다.

   9. 카탈로그 데이터의 반복 업로드를 예약할지 여부를 선택합니다.

   10. 카탈로그를 처음 가져오거나 카탈로그를 삭제한 후 다시 가져오는 경우 제품 수준을 선택합니다. 제품 수준 자세히 알아보기

       데이터를 가져온 후에 제품 수준 구성을 변경하려면 상당한 노력이 필요합니다.

   11. 가져오기를 클릭합니다.

   curl

   1. 카탈로그를 처음 업로드하거나 카탈로그를 삭제한 후 다시 가져오는 경우 Catalog.patch 메서드를 사용하여 제품 수준을 설정합니다. 이 작업을 수행하려면 Retail 관리자 역할이 필요합니다. 제품 수준 자세히 알아보기

      • ingestionProductType: primary(기본값) 및 variant 값을 지원합니다.
      • merchantCenterProductIdField: offerId(기본값) 및 itemGroupId 값을 지원합니다. 판매자 센터를 사용하지 않는 경우 기본값 offerId로 설정합니다.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "productLevelConfig": {
        "ingestionProductType": "PRODUCT_TYPE",
        "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
      }
      }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Products.import 메서드를 사용하여 카탈로그를 가져옵니다.

      • DATASET_ID: BigQuery 데이터 세트의 ID입니다.
      • TABLE_ID: 데이터를 보관하는 BigQuery 테이블의 ID입니다.
      • STAGING_DIRECTORY: 선택사항. 데이터를 BigQuery로 가져오기 전에 데이터의 중간 위치로 사용되는 Cloud Storage 디렉터리입니다. 임시 디렉터리를 자동으로 만들려면 이 필드를 비워둡니다(추천).
      • ERROR_DIRECTORY: 선택사항. 가져오기에 대한 오류 정보를 볼 수 있는 Cloud Storage 디렉터리입니다. 임시 디렉터리를 자동으로 만들려면 이 필드를 비워둡니다(추천).
      • dataSchema: dataSchema 속성에 product_merchant_center 값을 사용합니다. 판매자 센터 제품 테이블 스키마를 참조하세요.

      스테이징 또는 오류 디렉터리를 지정하지 않는 것이 좋습니다. 이렇게 하면 새 스테이징 및 오류 디렉터리가 있는 Cloud Storage 버킷을 자동으로 만들 수 있습니다. 이러한 디렉터리는 BigQuery 데이터 세트와 동일한 리전에서 생성되며 각 가져오기마다 고유합니다. 따라서 스테이징 데이터를 동일한 디렉터리로 가져오는 여러 작업이 방지되고 동일한 데이터 다시 가져오기가 방지됩니다. 3일이 지나면 버킷 및 디렉터리가 자동으로 삭제되어 스토리지 비용이 감소합니다.

      자동으로 생성된 버킷 이름에는 프로젝트 ID, 버킷 리전, 데이터 스키마 이름이 밑줄로 구분되어 있습니다(예: 4321_us_catalog_retail). 자동으로 생성된 디렉터리는 staging 또는 errors라고 하며 숫자가 추가됩니다(예: staging2345 또는 errors5678).

      디렉터리를 지정하는 경우 Cloud Storage 버킷이 BigQuery 데이터 세트와 같은 리전에 있어야 합니다. 그렇지 않으면 가져오기가 실패합니다. 스테이징 및 오류 디렉터리를 gs://<bucket>/<folder>/ 형식으로 지정합니다. 두 디렉터리는 서로 달라야 합니다.

     curl -X POST \
          -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
          -H "Content-Type: application/json; charset=utf-8" \
          --data '{
            "inputConfig":{
               "bigQuerySource": {
                 "datasetId":"DATASET_ID",
                 "tableId":"TABLE_ID",
                 "dataSchema":"product_merchant_center"
               }
             }
         }' \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

BigQuery에서 카탈로그 데이터 가져오기

BigQuery에서 올바른 형식으로 카탈로그 데이터를 가져오려면 Vertex AI Search for Retail 스키마를 사용해서 올바른 형식으로 BigQuery 테이블을 만들고 빈 테이블에 카탈로그 데이터를 로드합니다. 그런 후 Vertex AI Search for Retail에 데이터를 업로드합니다.

BigQuery 테이블에 대한 도움말은 테이블 소개를 참조하세요. BigQuery 쿼리에 대한 도움말은 BigQuery 데이터 쿼리 개요를 참조하세요.

Cloud Shell 편집기에서 이 태스크의 단계별 안내를 직접 수행하려면 둘러보기를 클릭합니다.

둘러보기

카탈로그를 가져오려면 다음 안내를 따르세요.

1. BigQuery 데이터 세트가 다른 프로젝트에 있으면 Vertex AI Search for Retail이 BigQuery 데이터 세트에 액세스할 수 있도록 필요한 권한을 구성합니다. 자세히 알아보기

2. 카탈로그 데이터를 Vertex AI Search for Retail로 가져옵니다.

   콘솔

   1. Search for Retail 콘솔에서 데이터> 페이지로 이동합니다.
      
      데이터 페이지로 이동
   2. 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
   3. 제품 카탈로그를 선택합니다.
   4. 데이터 소스로 BigQuery를 선택합니다.
   5. 카탈로그를 업로드할 브랜치를 선택합니다.
   6. Retail 제품 카탈로그 스키마를 선택합니다. 이는 Vertex AI Search for Retail을 위한 제품 스키마입니다.
   7. 데이터가 있는 BigQuery 테이블을 입력합니다.
   8. 선택사항: 고급 옵션 표시에서 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.
      
      지정하지 않으면 기본 위치가 사용됩니다. 지정하면 BigQuery 및 Cloud Storage 버킷은 같은 리전에 있어야 합니다.
   9. Search를 사용 설정하지 않고 판매자 센터 스키마를 사용하는 경우 제품 수준을 선택합니다.
      
      처음 카탈로그를 가져오거나 카탈로그를 삭제한 후 다시 가져오는 경우 제품 수준을 선택해야 합니다. 제품 수준 자세히 알아보기 데이터를 가져온 후에 제품 수준을 변경하려면 상당한 노력이 필요합니다.
      
      중요: 변형으로 수집된 제품 카탈로그가 있는 프로젝트에는 검색을 사용 설정할 수 없습니다.
   10. 가져오기를 클릭합니다.

   curl

   1. 카탈로그를 처음 업로드하거나 카탈로그를 삭제한 후 다시 가져오는 경우 Catalog.patch 메서드를 사용하여 제품 수준을 설정합니다. 이 작업을 수행하려면 Retail 관리자 역할이 필요합니다.

      • ingestionProductType: primary(기본값) 및 variant 값을 지원합니다.
      • merchantCenterProductIdField: offerId 및 itemGroupId 값을 지원합니다. 판매자 센터를 사용하지 않는 경우에는 이 필드를 설정할 필요가 없습니다.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. 가져오기의 입력 매개변수에 대한 데이터 파일을 만듭니다.

      BigQuerySource 객체를 사용하여 BigQuery 데이터 세트를 가리킵니다.

      • DATASET_ID: BigQuery 데이터 세트의 ID입니다.
      • TABLE_ID: 데이터를 보관하는 BigQuery 테이블의 ID입니다.
      • PROJECT_ID: BigQuery 소스가 있는 프로젝트 ID입니다. 지정하지 않으면 프로젝트 ID가 상위 요청에서 상속됩니다.
      • STAGING_DIRECTORY: 선택사항. 데이터를 BigQuery로 가져오기 전에 데이터의 중간 위치로 사용되는 Cloud Storage 디렉터리입니다. 임시 디렉터리를 자동으로 만들려면 이 필드를 비워둡니다(추천).
      • ERROR_DIRECTORY: 선택사항. 가져오기에 대한 오류 정보를 볼 수 있는 Cloud Storage 디렉터리입니다. 임시 디렉터리를 자동으로 만들려면 이 필드를 비워둡니다(추천).
      • dataSchema: dataSchema 속성에 product(기본값) 값을 사용합니다. Vertex AI Search for Retail 스키마를 사용합니다.

      스테이징 또는 오류 디렉터리를 지정하지 않는 것이 좋습니다. 이렇게 하면 새 스테이징 및 오류 디렉터리가 있는 Cloud Storage 버킷을 자동으로 만들 수 있습니다. 이러한 디렉터리는 BigQuery 데이터 세트와 동일한 리전에서 생성되며 각 가져오기마다 고유합니다. 따라서 스테이징 데이터를 동일한 디렉터리로 가져오는 여러 작업이 방지되고 동일한 데이터 다시 가져오기가 방지됩니다. 3일이 지나면 버킷 및 디렉터리가 자동으로 삭제되어 스토리지 비용이 감소합니다.

      자동으로 생성된 버킷 이름에는 프로젝트 ID, 버킷 리전, 데이터 스키마 이름이 밑줄로 구분되어 있습니다(예: 4321_us_catalog_retail). 자동으로 생성된 디렉터리는 staging 또는 errors라고 하며 숫자가 추가됩니다(예: staging2345 또는 errors5678).

      디렉터리를 지정하는 경우 Cloud Storage 버킷이 BigQuery 데이터 세트와 같은 리전에 있어야 합니다. 그렇지 않으면 가져오기가 실패합니다. 스테이징 및 오류 디렉터리를 gs://<bucket>/<folder>/ 형식으로 지정합니다. 두 디렉터리는 서로 달라야 합니다.

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }

   3. Products:import REST 메서드에 POST 요청을 수행하여 카탈로그 정보를 가져오고 데이터 파일의 이름을 제공합니다(여기에서는 input.json으로 표시됨).

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      API를 사용하여 프로그래매틱 방식으로 상태를 확인할 수 있습니다. 다음과 같은 응답 객체가 수신됩니다.

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      이름 필드는 작업 객체의 ID입니다. 이 객체 상태를 요청하려면 done 필드가 true로 반환될 때까지 이름 필드를 import 메서드에서 반환한 값으로 바꿉니다.

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"

      작업이 완료되면 반환된 객체의 done 값이 true가 되며 다음 예시와 비슷한 상태 객체가 포함됩니다.

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Cloud Storage의 오류 디렉터리에서 파일을 검사하여 가져오기 중에 오류가 발생했는지 여부를 검사할 수 있습니다.

BigQuery 데이터 세트에 대한 액세스 설정

BigQuery 데이터 세트가 Vertex AI Search for Retail 서비스와 다른 프로젝트에 있을 때 액세스를 설정하려면 다음 단계를 수행합니다.

1. Google Cloud 콘솔에서 IAM 페이지를 엽니다.

   IAM 페이지 열기

2. Vertex AI Search for Retail 프로젝트를 선택합니다.

3. 이름이 Retail 서비스 계정인 서비스 계정을 찾습니다.

   가져오기 작업을 이전에 시작한 적이 없으면 이 서비스 계정이 나열되지 않을 수 있습니다. 이 서비스 계정이 표시되지 않으면 가져오기 태스크로 돌아가서 가져오기를 시작합니다. 권한 오류로 인해 가져오기가 실패하면 여기로 돌아와 이 작업을 완료하세요.

4. 이메일 주소와 비슷한 서비스 계정의 식별자를 복사합니다(예: service-525@gcp-sa-retail.iam.gserviceaccount.com).

5. 동일한 IAM 및 관리자 페이지에서 BigQuery 프로젝트로 전환하고 person_add 액세스 권한 부여를 클릭합니다.

6. 새 주 구성원에 대해 Vertex AI Search for Retail 서비스 계정의 식별자를 입력하고 BigQuery > BigQuery 사용자 역할을 선택합니다.

7. 다른 역할 추가를 클릭하고 BigQuery > BigQuery 데이터 편집자를 선택합니다.

   전체 프로젝트에 데이터 편집자 역할을 제공하지 않으려면 이 역할을 데이터 세트에 직접 추가하면 됩니다. 자세히 알아보기

8. 저장을 클릭합니다.

Cloud Storage에서 카탈로그 데이터 가져오기

카탈로그 데이터를 JSON 형식으로 가져오려면 가져올 카탈로그 데이터가 포함된 JSON 파일을 하나 이상 만들어 Cloud Storage에 업로드합니다. 여기에서 이를 Vertex AI Search for Retail로 가져올 수 있습니다.

JSON 제품 항목 형식의 예시는 제품 항목 JSON 데이터 형식을 참조하세요.

Cloud Storage에의 파일 업로드 관련 도움말은 객체 업로드를 참조하세요.

1. Vertex AI Search for Retail 서비스 계정에 버킷 읽기 및 쓰기 권한이 있는지 확인합니다.

   Vertex AI Search for Retail 서비스 계정은 Google Cloud 콘솔에서 Retail 서비스 계정 이름으로 IAM 페이지에 나열됩니다. 계정을 버킷 권한에 추가할 때는 이메일 주소와 비슷한 서비스 계정 식별자 (예: service-525@gcp-sa-retail.iam.gserviceaccount.com)를 사용합니다.

2. 카탈로그 데이터를 가져옵니다.

   콘솔

   1. Search for Retail 콘솔에서 데이터> 페이지로 이동합니다.
      
      데이터 페이지로 이동
   2. 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
   3. 데이터 소스로 제품 카탈로그를 선택합니다.
   4. 카탈로그를 업로드할 브랜치를 선택합니다.
   5. Retail 제품 카탈로그 스키마를 스키마로 선택합니다.
   6. 데이터의 Cloud Storage 위치를 입력합니다.
   7. Search를 사용 설정하지 않은 경우 제품 수준을 선택합니다.
      
      카탈로그를 처음으로 가져오거나 카탈로그를 삭제한 후 다시 가져오는 경우 제품 수준을 선택해야 합니다. 제품 수준 자세히 알아보기 데이터를 가져온 후에 제품 수준을 변경하려면 상당한 노력이 필요합니다.
      
      중요: 변형으로 수집된 제품 카탈로그가 있는 프로젝트에는 검색을 사용 설정할 수 없습니다.
   8. 가져오기를 클릭합니다.

   curl

   1. 카탈로그를 처음 업로드하거나 카탈로그를 삭제한 후 다시 가져오는 경우 Catalog.patch 메서드를 사용하여 제품 수준을 설정합니다. 제품 수준 자세히 알아보기

      • ingestionProductType: primary(기본값) 및 variant 값을 지원합니다.
      • merchantCenterProductIdField: offerId 및 itemGroupId 값을 지원합니다. 판매자 센터를 사용하지 않는 경우에는 이 필드를 설정할 필요가 없습니다.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. 가져오기의 입력 매개변수에 대한 데이터 파일을 만듭니다. GcsSource 객체를 사용하여 Cloud Storage 버킷을 가리킵니다.

      파일은 여러 개 제공하거나 하나만 제공할 수도 있습니다. 이 예시에서는 2개의 파일을 사용합니다.

      • INPUT_FILE: 카탈로그 데이터가 포함된 Cloud Storage의 파일입니다.
      • ERROR_DIRECTORY: 가져오기에 대한 오류 정보를 볼 수 있는 Cloud Storage 디렉터리입니다.

      입력 파일 필드는 gs://<bucket>/<path-to-file>/ 형식이어야 합니다. 오류 디렉터리는 gs://<bucket>/<folder>/ 형식이어야 합니다. 오류 디렉터리가 존재하지 않으면 생성됩니다. 버킷은 이미 있어야 합니다.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }

   3. Products:import REST 메서드에 POST 요청을 수행하여 카탈로그 정보를 가져오고 데이터 파일의 이름을 제공합니다(여기에서는 input.json으로 표시됨).

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      가져오기 작업의 상태를 확인하는 가장 쉬운 방법은 Google Cloud 콘솔을 사용하는 것입니다. 자세한 내용은 특정 통합 작업의 상태 보기를 참조하세요.

      API를 사용하여 프로그래매틱 방식으로 상태를 확인할 수도 있습니다. 다음과 같은 응답 객체가 수신됩니다.

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      이름 필드는 작업 객체의 ID입니다. 이 객체의 상태를 요청하고 done 필드가 true로 반환될 때까지 이름 필드를 가져오기 메서드에서 반환한 값으로 바꿉니다.

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"

      작업이 완료되면 반환된 객체의 done 값이 true가 되며 다음 예시와 비슷한 상태 객체가 포함됩니다.

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Cloud Storage의 오류 디렉터리에 있는 파일을 검사하면 가져오기 중에 발생한 오류의 종류를 확인할 수 있습니다.

인라인으로 카탈로그 데이터 가져오기

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

제품 항목 JSON 데이터 형식

JSON 파일의 Product 항목은 다음 예시와 유사합니다.

전체 제품을 한 줄에 제공합니다. 각 제품은 한 줄에 하나만 입력되어야 합니다.

최소 필수 입력란:

  {
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers"
  }
  {
    "id": "5839",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt"
  }

전체 객체:

  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers",
    "description": "Sneakers for the rest of us",
    "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
    },
    "availableTime": "2020-01-01T03:33:33.000001Z",
    "availableQuantity": "1",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

이전 카탈로그 데이터

Vertex AI Search for Retail은 이전 카탈로그 데이터 가져오기 및 관리를 지원합니다. 이전 카탈로그 데이터는 모델 학습에 이전 사용자 이벤트를 사용할 때 유용할 수 있습니다. 과거 제품 정보를 사용하면 이전 사용자 이벤트 데이터를 강화하고 모델 정확도를 향상시킬 수 있습니다.

이전 제품은 만료된 제품으로 저장됩니다. 이는 검색 응답에서 반환되지 않지만 Update, List, Delete API 호출에 표시됩니다.

이전 카탈로그 데이터 가져오기

제품의 expireTime 필드가 과거 타임스탬프로 설정되면 이 제품은 이전 제품으로 간주됩니다. 추천에 영향을 주지 않도록 제품 재고를 OUT_OF_STOCK으로 설정합니다.

이전 카탈로그 데이터를 가져오려면 다음 방법을 사용하는 것이 좋습니다.

• Product.Create 메서드 호출.
• 만료된 제품 인라인 가져오기.
• BigQuery에서 만료된 제품 가져오기.

Product.Create 메서드 호출

Product.Create 메서드를 사용하여 expireTime 필드가 과거 타임스탬프로 설정된 Product 항목을 만듭니다.

만료된 제품 인라인 가져오기

이 단계는 제품에 expireTime 필드가 과거 타임스탬프로 설정되어야 한다는 점을 제외하고 인라인 가져오기와 동일합니다.

전체 제품을 한 줄에 제공합니다. 각 제품은 한 줄에 하나만 입력되어야 합니다.

다음은 인라인 가져오기 요청에 사용된 ./data.json의 예시입니다.

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

BigQuery 또는 Cloud Storage에서 만료된 제품 가져오기

BigQuery에서 카탈로그 데이터 가져오기 또는 Cloud Storage에서 카탈로그 데이터 가져오기에 설명된 것과 동일한 절차를 사용합니다. 하지만 expireTime 필드를 과거의 타임스탬프로 설정해야 합니다.

카탈로그를 최신 상태로 유지

최상의 결과를 얻으려면 카탈로그에 현재 정보가 포함되어야 합니다. 카탈로그가 최신 상태를 유지하도록 매일 카탈로그를 가져오는 것이 좋습니다. Google Cloud Scheduler를 사용하여 가져오기를 예약하거나 Google Cloud 콘솔을 사용하여 데이터를 가져올 때 자동 예약 옵션을 선택할 수 있습니다.

신규 또는 변경된 제품 항목만 업데이트하거나 전체 카탈로그를 가져올 수 있습니다. 이미 카탈로그에 있는 제품을 가져올 경우 다시 추가되지 않습니다. 변경된 모든 항목은 업데이트됩니다.

단일 상품을 업데이트하려면 제품 정보 업데이트를 참조하세요.

일괄 업데이트

가져오기 메서드를 사용하여 카탈로그를 일괄 업데이트할 수 있습니다. 이 작업은 초기 가져오기를 수행할 때와 동일한 방식으로 실행합니다. 카탈로그 데이터 가져오기의 단계를 따르세요.

가져오기 상태 모니터링

카탈로그 수집 및 상태를 모니터링하려면 다음 안내를 따르세요.

1. 카탈로그에 대한 집계된 정보를 확인하고 Search for Retail 데이터 데이터의 카탈로그 탭에서 업로드된 제품을 미리봅니다.

   데이터 페이지로 이동

2. 검색 결과 품질을 개선하고 데이터 품질 페이지에서 검색 성능 등급을 잠금 해제하기 위해 카탈로그 데이터를 업데이트해야 하는지 평가합니다.

   검색 데이터 품질을 확인하고 검색 성능 등급을 보는 방법에 대한 자세한 내용은 검색 성능 등급 잠금 해제를 참조하세요. 이 페이지에서 사용 가능한 카탈로그 측정항목에 대한 요약은 카탈로그 품질 측정항목을 참조하세요.

   데이터 품질 페이지로 이동

3. 데이터 업로드에 문제가 있는지 알려주는 알림을 만들려면 Cloud Monitoring 알림 설정 절차를 따르세요.

   고품질 결과를 가져오려면 카탈로그를 최신 상태로 유지해야 합니다. 알림을 사용하여 가져오기 오류율을 모니터링하고 필요한 경우 조치를 취합니다.

다음 단계

• 사용자 이벤트 기록 시작
• 카탈로그에 대한 합산 데이터 보기
• 데이터 업로드 알림 설정