이 문서는 Recommendations AI, Retail Search, 새로운 Retail 콘솔에 대한 문서입니다. 제한된 GA 단계에서 Retail Search를 사용하려면 Cloud 영업팀에 문의하세요.

Recommendations AI만 사용하는 경우 Recommendations 콘솔에서 Recommendations AI 문서를 참조하세요.

카탈로그 정보 가져오기

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

이 페이지의 가져오기 절차는 Recommendations AI 및 Retail Search 모두에 적용됩니다. 데이터를 Retail API로 가져오면 두 서비스 모두에서 해당 데이터를 사용할 수 있으므로 두 서비스를 모두 사용하는 경우 동일한 데이터를 두 번 가져오지 않아도 됩니다.

시작하기 전에

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

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

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

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

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

  • 데이터를 업로드하기 전에 제품 수준 정보를 검토하세요.

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

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

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

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

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

    더미 또는 자리표시자 값을 사용하지 않습니다.

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

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

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

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

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

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

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

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

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

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

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

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

Cloud Storage 설명 Cloud Storage 버킷에 로드된 파일에서 JSON 형식으로 데이터를 가져옵니다. 각 파일은 2GB 이하여야 하고 한 번에 최대 100개까지 파일을 가져올 수 있습니다. 가져오기는 Cloud Console 또는 curl을 사용하여 수행될 수 있습니다. 커스텀 속성을 허용하는 Product JSON 데이터 형식을 사용합니다.
사용 시기 한 번에 많은 양의 데이터를 로드해야 하는 경우.
제한사항 변경사항이 즉시 반영되지 않기 때문에 인벤토리 및 가격이 자주 업데이트되는 카탈로그에는 적합하지 않습니다.
BigQuery 설명 Retail 스키마를 사용하는 이전에 로드된 BigQuery 테이블에서 데이터를 가져옵니다. Cloud Console 또는 curl을 사용하여 수행될 수 있습니다.
사용 시기 많은 속성이 포함된 제품 카탈로그가 있는 경우입니다. BigQuery는 키-값 커스텀 속성을 포함하여 다른 가져오기 옵션보다 많은 제품 속성이 포함된 Retail 스키마를 사용합니다.

대량 볼륨이 포함된 경우입니다. BigQuery 가져오기는 데이터 한도가 없습니다.

이미 BigQuery를 사용하는 경우입니다.
제한사항 Retail 스키마에 매핑되는 BigQuery 테이블을 만드는 추가 단계가 필요합니다.
판매자 센터 동기화 설명 계정을 Retail API에 연결하여 판매자 센터를 통해 카탈로그 데이터를 가져옵니다. 연결 후에는 판매자 센터의 카탈로그 데이터 업데이트가 실시간으로 Retail API에 동기화됩니다.
사용 시기 판매자 센터와의 기존 통합이 있는 경우.
제한사항 스키마 지원이 제한됩니다. 예를 들어 판매자 센터에서 제품 컬렉션이 지원되지 않습니다. 판매자 센터는 연결 해제될 때까지 데이터의 신뢰 소스가 되므로, 필요한 모든 커스텀 속성을 판매자 센터 데이터에 추가해야 합니다.

제어가 제한됩니다. 판매자 센터에서 가져올 특정 필드 또는 항목 집합을 지정할 수 없습니다. 판매자 센터에 있는 모든 항목 및 필드를 가져옵니다.
인라인 가져오기 설명 Product.import 메서드 호출을 사용하여 가져옵니다. Retail 스키마보다 적은 제품 카탈로그 속성이 포함된 ProductInlineSource 객체를 사용하지만 커스텀 속성을 지원합니다.
사용 시기 비관계형 플랫 카탈로그 데이터가 있거나 수량 또는 가격 업데이트 빈도가 높은 경우.
제한사항 한 번에 100개 이하의 카탈로그 항목만 가져올 수 있습니다. 그러나 많은 로드 단계를 수행할 수 있습니다. 항목 한도가 없습니다.

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

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

다음과 같은 방법으로 판매자 센터에서 카탈로그 데이터를 가져올 수 있습니다.

  • 일회성 절차로 일괄 가져오기(Recommendations AI만 해당)

  • 판매자 센터 계정을 Retail API에 연결합니다. 연결하면 판매자 센터 계정의 변경사항이 Retail API에 지속적으로 동기화됩니다.

판매자 센터에서 대량 가져오기

Retail Cloud Console이나 products.import 메서드를 사용하여 판매자 센터에서 카탈로그 데이터를 가져올 수 있습니다. 일괄 가져오기는 일회성 절차이며 Recommendations AI에서만 지원됩니다.

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

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

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

  2. BigQuery 데이터 세트가 다른 프로젝트에 있는 경우 Retail API가 BigQuery 데이터 세트에 액세스할 수 있도록 필요한 권한을 구성합니다. 자세히 알아보기

  3. BigQuery에서 Retail API로 카탈로그 데이터를 가져옵니다.

    Console

    1. Google Cloud Console의 Retail 데이터 페이지로 이동합니다.

      데이터 페이지로 이동

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

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

    4. 카탈로그를 업로드할 분기를 선택합니다.

    5. 데이터 소스로 판매자 센터를 선택하고 업로드 방법으로 BigQuery를 선택합니다.

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

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

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

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

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

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

    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. Products.import 메서드를 사용하여 카탈로그를 가져옵니다.

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

      Retail API가 새 스테이징 및 오류 디렉터리로 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"
    

Retail API에 판매자 센터 연결

판매자 센터와 Retail API 사이의 지속적인 동기화를 위해 Merchant Center 계정을 Retail API에 연결할 수 있습니다. 연결되면 판매자 센터 계정의 카탈로그 정보를 Retail API로 즉시 가져옵니다.

Retail API가 판매자 센터 계정에 연결된 동안 판매자 센터 계정의 제품 데이터가 변경되면 Retail API에서도 몇 분 내에 자동으로 업데이트됩니다. 판매자 센터 변경사항이 Retail API에 동기화되지 않도록 하려면 판매자 센터 계정을 연결 해제할 수 있습니다.

판매자 센터 계정을 연결 해제해도 Retail API의 제품은 삭제되지 않습니다. 가져온 제품을 삭제하려면 제품 정보 삭제를 참조하세요.

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

Console

  1. Google Cloud Console의 Retail 데이터 페이지로 이동합니다.

    데이터 페이지로 이동

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

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

  4. 데이터 소스로 판매자 센터 동기화를 선택합니다.

  5. 판매자 센터 계정을 선택합니다.

  6. 가져올 판매자 센터 대상을 선택합니다.

  7. 카탈로그를 업로드할 분기를 선택합니다.

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

curl

  1. 로컬 환경의 서비스 계정이 판매자 센터 계정 및 Retail API에 모두 액세스할 수 있는지 확인합니다. 판매자 센터 계정에 액세스할 수 있는 계정을 확인하려면 판매자 센터의 사용자 계정을 참조하세요.

  2. Catalog.patch 메서드를 사용하여 링크를 설정합니다.

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
     --data '{
        "merchantCenterLinkingConfig": {
          "links": [{
             merchantCenterAccountId: MERCHANT_CENTER_ID,
             destinations: ["DESTINATION_1", "DESTINATION_2", ...]
             branchId: "BRANCH_ID"
          }]
        }
     }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog?updateMask=merchantCenterLinkingConfig"
    
    • MERCHANT_CENTER_ID: 판매자 센터 계정의 ID입니다.
    • BRANCH_ID: 연결을 설정할 분기의 ID입니다. '0', '1' 또는 '2' 값을 수락합니다.
    • DESTINATION: 판매자 센터 대상입니다. 대상 값을 1개 이상 추가해야 합니다. 판매자 센터 대상 문서에 나열된 지원되는 값의 조합을 사용할 수 있습니다.

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

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

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

Console

  1. Google Cloud Console의 Retail 데이터 페이지로 이동합니다.

    데이터 페이지로 이동

  2. 페이지 오른쪽 위에 있는 판매자 센터 버튼을 클릭하여 연결된 판매자 센터 계정 목록을 엽니다.

  3. 연결 해제하려는 판매자 센터 계정 옆에 있는 연결 해제를 클릭하여 대화상자에서 표시된 옵션을 확인합니다.

curl

Catalog.patch 메서드를 사용하여 Catalog 리소스에서 연결 구성을 삭제합니다.

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

판매자 센터 연결 제한사항

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

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

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

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

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

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

BigQuery에서 올바른 형식으로 카탈로그 데이터를 가져오려면 올바른 형식의 Retrail 스키마~BigQuery 테이블 만들기를 사용하고 카탈로그 데이터로 빈 테이블을 로드합니다. 그런 다음 데이터를 Retail API에 업로드합니다.

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

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

  1. BigQuery 데이터 세트가 다른 프로젝트에 있는 경우 Retail API가 BigQuery 데이터 세트에 액세스할 수 있도록 필요한 권한을 구성합니다. 자세히 알아보기

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

    Console

    1. Google Cloud Console의 Retail 데이터 페이지로 이동합니다.

      데이터 페이지로 이동

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

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

    4. 카탈로그를 업로드할 분기를 선택합니다.

    5. BigQuery를 데이터 소스로, Retail 제품 카탈로그 스키마를 스키마로 선택합니다.

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

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

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

    8. (선택사항) 카탈로그 반복 업로드를 예약할지 여부를 선택합니다.

      이 옵션은 Retail API로 카탈로그를 한 번 이상 성공적으로 가져온 경우에만 사용할 수 있습니다.

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

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

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

    curl

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

      • ingestionProductType: primary(기본값) 및 variant 값을 지원합니다.
      • merchantCenterProductIdField: offerIditemGroupId 값을 지원합니다. 판매자 센터를 사용하지 않는 경우에는 이 필드를 설정할 필요가 없습니다.
      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 디렉터리입니다. Retail API가 임시 디렉터리를 자동으로 생성하도록 하려면 이 필드를 비워 두세요(권장).
      • ERROR_DIRECTORY: 선택사항. 가져오기에 대한 오류 정보를 볼 수 있는 Cloud Storage 디렉터리입니다. Retail API가 임시 디렉터리를 자동으로 생성하도록 하려면 이 필드를 비워 두세요(권장).
      • dataSchema: dataSchema 속성에 product(기본값) 값을 사용합니다. Retail 스키마를 사용합니다.

      Retail API가 새 스테이징 및 오류 디렉터리로 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)을 지정하여 Retail API에 카탈로그 정보를 가져옵니다.

      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 데이터 세트가 Retail 서비스와 다른 프로젝트에 있을 때 액세스를 설정하려면 다음 단계를 완료합니다.

  1. Cloud Console에서 IAM 페이지를 엽니다.

    IAM 페이지 열기

  2. Retail 프로젝트를 선택합니다.

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

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

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

  5. 동일한 IAM 및 관리자 페이지에서 BigQuery 프로젝트로 전환하고 추가를 클릭합니다.

  6. Retail 서비스 계정의 식별자를 입력하고 BigQuery > BigQuery 사용자 역할을 선택합니다.

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

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

  8. 저장을 클릭합니다.

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

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

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

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

  1. Retail 서비스 계정에 버킷을 읽고 쓸 수 있는 권한이 있는지 확인합니다.

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

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

    Console

    1. Google Cloud Console의 Retail 데이터 페이지로 이동합니다.

      데이터 페이지로 이동

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

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

    4. 카탈로그를 업로드할 분기를 선택합니다.

    5. 데이터 소스로 Cloud Storage를 선택하고 스키마로 Retail 제품 카탈로그 스키마를 선택합니다.

    6. 데이터의 Cloud Storage 위치를 입력합니다.

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

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

    8. (선택사항) 카탈로그 반복 업로드를 예약할지 여부를 선택합니다.

      이 옵션은 Retail API로 카탈로그를 한 번 이상 성공적으로 가져온 경우에만 사용할 수 있습니다.

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

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

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

    curl

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

      • ingestionProductType: primary(기본값) 및 variant 값을 지원합니다.
      • merchantCenterProductIdField: offerIditemGroupId 값을 지원합니다. 판매자 센터를 사용하지 않는 경우에는 이 필드를 설정할 필요가 없습니다.
      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>/ 형식이어야 합니다. 오류 디렉터리가 존재하지 않으면 Retail API가 해당 디렉터리를 만듭니다. 버킷은 이미 있어야 합니다.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }
      
    3. Products:import REST 메서드에 POST 요청을 하고 데이터 파일의 이름(여기에서는 input.json)을 지정하여 카탈로그 정보를 Retail API로 가져옵니다.

      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"
      

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

      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의 오류 디렉터리에 있는 파일을 검사하면 가져오기 중에 발생한 오류의 종류를 확인할 수 있습니다.

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

curl

카탈로그 데이터를 지정하기 위해 productInlineSource 객체를 사용하여 Products:import REST 메서드에 POST 요청을 수행함으로써 Retail API 인라인으로 카탈로그 정보를 가져옵니다.

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

  1. 제품의 JSON 파일을 만들고 ./data.json이라는 이름을 지정합니다.

    {
    "inputConfig": {
    "productInlineSource": {
      "products": [
        {
          <product1>
        },
        {
          <product2>
        },
        ....
      ]
    }
    }
    }
    
  2. POST 메서드 호출:

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

자바

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 }]
}

이전 카탈로그 데이터

Retail API는 이전 카탈로그 데이터 가져오기 및 관리를 지원합니다. 이전 카탈로그 데이터는 모델 학습에 이전 사용자 이벤트를 사용할 때 유용할 수 있습니다. Retail API는 이전 제품 정보를 사용하여 이전 사용자 이벤트 데이터를 보강하고 모델 정확성을 개선할 수 있습니다.

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

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

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

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

Product.Create 메서드 호출

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

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

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

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

{
"inputConfig": {
  "productInlineSource": {
      "products": [
        {
          "name": "historical product 001"
          "id": "historical_product_001"
          "name": "A historical product"
          "expire_time": {
            "second": 1000000000  // a past timestamp
          }
        },
        {
          <Another product>
        },
        ....
      ]
    }
  }
}

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

이 절차는 BigQuery 또는 Cloud Storage에서 일반 제품을 가져오는 것과 유사합니다. 하지만 expireTime 필드를 과거의 타임스탬프로 설정해야 합니다.

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

Retail API는 최상의 결과를 제공하기 위해 최신 제품 정보를 사용합니다. 카탈로그가 최신 상태를 유지하도록 매일 카탈로그를 가져오는 것이 좋습니다. Google Cloud Scheduler를 사용하여 가져오기를 예약하거나 Cloud Console을 사용하여 데이터를 가져올 때 자동 예약 옵션을 선택할 수 있습니다.

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

단일 항목을 업데이트하려면 카탈로그 정보 업데이트를 참조하세요.

일괄 업데이트

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

가져오기 상태 모니터링

가져온 데이터에 오류가 없는지 확인하려면 Retail 데이터 페이지에서 카탈로그의 데이터 로드 측정항목을 확인합니다. Retail 데이터 페이지에는 카탈로그에 있는 제품 데이터의 품질 측정항목도 표시됩니다.

고품질의 결과를 받으려면 카탈로그를 최신 상태로 유지하는 것이 중요합니다. 가져오기 오류율을 모니터링하고 필요하다면 조치를 취해야 합니다. 자세한 내용은 알림 설정을 참조하세요.

다음 단계