개요

Cloud Retail 서비스와 Retail API를 사용하면 고객이 머신러닝, 추천 시스템 또는 Google Cloud에 대한 높은 수준의 전문 지식 없이도 맞춤설정된 엔드 투 엔드 추천 시스템을 빌드할 수 있습니다. Retail API 제품 추천 및 제품 검색 서비스를 사용하려면 제품 카탈로그 데이터 및 해당 카탈로그와 관련된 사용자 이벤트 데이터를 만들거나 가져와야 합니다.

이 실습에서는 다양한 기법으로 제품 카탈로그 및 사용자 이벤트 데이터를 업로드하여 Retail Recommendations AI 및 제품 검색 서비스를 위한 환경을 준비합니다. 일반적인 데이터 수집 오류를 살펴보고 Cloud 콘솔과 Retail API를 사용하여 소매업 카탈로그 및 이벤트 데이터를 검토합니다.

이 실습에서는 제품 카탈로그로 Google 판매자 센터 데이터 세트의 하위 집합을 사용합니다. Google 판매자 센터에서 직접 내보내기된 데이터는 Retail 데이터 수집 API와 호환되지 않는 스키마를 사용하므로, 실습에서 사용되는 데이터 세트는 Retail Schema를 준수하도록 수정되었습니다.

목표

이 실습에서는 다음 작업을 진행하는 방법을 알아봅니다.

• Retail API를 사용 설정합니다.
• BigQuery와 Cloud Storage에서 제품 카탈로그 및 사용자 이벤트 데이터를 가져옵니다.
• 데이터 가져오기 이벤트 및 오류를 검토합니다.
• 제품 카탈로그 및 사용자 이벤트 데이터를 검토합니다.
• Retail API를 사용하여 사용자 이벤트 데이터를 업로드합니다.

설정 및 요건

실습 설정

각 실습에서는 정해진 기간 동안 새 Google Cloud 프로젝트와 리소스 집합이 무료로 제공됩니다.

1. 시크릿 창을 사용하여 Qwiklabs에 로그인합니다.

2. 실습 사용 가능 시간(예: 1:15:00)을 참고하여 해당 시간 내에 완료합니다.
   일시중지 기능은 없습니다. 필요한 경우 다시 시작할 수 있지만 처음부터 시작해야 합니다.

3. 준비가 되면 실습 시작을 클릭합니다.

4. 실습 사용자 인증 정보(사용자 이름 및 비밀번호)를 기록해 두세요. Google Cloud Console에 로그인합니다.

5. Google Console 열기를 클릭합니다.

6. 다른 계정 사용을 클릭한 다음, 안내 메시지에 이 실습에 대한 사용자 인증 정보를 복사하여 붙여넣습니다.
   다른 사용자 인증 정보를 사용하는 경우 오류가 발생하거나 요금이 부과됩니다.

7. 약관에 동의하고 리소스 복구 페이지를 건너뜁니다.

Cloud Shell 시작

Google Cloud에서는 자체 머신에서 Google Cloud를 원격으로 운영할 수 있습니다. 이 실습에서는 Google Cloud 콘솔과 Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 모두 사용합니다.

1. Cloud 콘솔에서 Cloud Shell 활성화를 클릭합니다.

   

   참고: 이전에 Cloud Shell을 시작하지 않았다면 설명이 포함된 중간 화면이 제공됩니다. 이 경우 계속을 클릭하면 중간 화면이 다시 표시되지 않습니다.

   이 일회성 화면은 다음과 같습니다.

   

   Cloud Shell을 프로비저닝하고 연결하는 작업은 몇 분이면 끝납니다.

   Cloud Shell은 클라우드에 호스팅된 가상 머신에 대한 터미널 액세스를 제공합니다. 필요한 모든 개발 도구는 가상 머신에 포함되어 있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 실습에서 대부분의 작업은 브라우저만 사용하여 Cloud 콘솔과 Cloud Shell을 통해 수행할 수 있습니다.

   Cloud Shell에 연결되면 인증이 완료되었고 프로젝트가 해당 프로젝트 ID로 이미 설정된 것을 볼 수 있습니다.

2. Cloud Shell에서 다음 명령어를 실행하여 인증되었는지 확인합니다.

   gcloud auth list

   출력:

   Credentialed Accounts ACTIVE: * ACCOUNT: {{{user_0.username| Lab User Name}}}

3. 활성 계정을 설정하려면 다음을 실행합니다.

   gcloud config set account {{{user_0.username| Lab User Name}}} 참고: gcloud 명령줄 도구는 Google Cloud의 강력한 통합 명령줄 도구입니다. 이 도구는 Cloud Shell에 사전 설치되어 있습니다. 여러 기능 중에서도 gcloud는 셸에서의 명령줄 자동 완성 기능을 지원합니다. 자세한 내용은 gcloud CLI 개요 가이드를 참고하세요.

4. 다음 명령어를 실행하여 실습을 위한 올바른 프로젝트를 사용 중인지 확인하세요.

   gcloud config list project

   출력:

   [core] project = {{{project_0.project_id | Project ID}}}

5. 올바른 프로젝트가 표시되지 않으면 다음 명령어로 설정할 수 있습니다.

   gcloud config set project {{{project_0.project_id| Project ID}}}

   출력:

   Updated property [core/project].

작업 1. Retail API 사용 설정하기

Retail Recommendations AI 또는 Retail Search API를 사용하려면 먼저 Retail API를 사용 설정해야 합니다.

1. 탐색 메뉴()에서 모든 제품 보기를 클릭하고 인공지능 섹션에서 상거래 검색을 선택합니다.

2. API 사용 설정을 클릭합니다.

3. 계속을 클릭하고 동의를 클릭하여 데이터 약관에 동의합니다.

4. 시작하기를 클릭합니다.

작업 2. 제품 카탈로그 및 사용자 이벤트 데이터 가져오기

이 작업에서는 BigQuery에서 제품 카탈로그 데이터를 가져오고 Cloud Storage에서 사용자 이벤트 데이터를 가져옵니다.

BigQuery에서 판매자 센터 제품 테이블 스키마 데이터 가져오기

merchant_center.products 테이블에는 Google 판매자 센터의 테스트 계정에서 Google 판매자 센터 제품 테이블 스키마를 사용하여 내보내기된 카탈로그 데이터가 들어 있습니다. 이 데이터 세트는 이전 Recommendations AI 콘솔 또는 API를 사용하여 카탈로그 데이터로 가져올 수 있습니다. Recommendations AI API를 대체하는 Retail API는 판매자 센터 제품 테이블 스키마를 사용하는 데이터의 가져오기를 현재 지원하지 않으며, 모든 데이터 가져오기는 Retail Schema를 사용해야 합니다. 단, 여기서는 데이터 가져오기 오류를 검토하는 방법을 알아보기 위해 Retail API를 사용하여 이 데이터의 가져오기를 시도해 볼 것입니다.

1. GCP 콘솔에서 상거래 검색 > 데이터를 클릭하여 소매업 데이터 관리 페이지를 엽니다.

2. 카탈로그 탭이 선택되어 있는지 확인한 후 가져오기를 클릭합니다.

3. 제품 카탈로그를 가져오기 위해 다음과 같이 가져오기 파라미터를 구성합니다.

   • 가져오기 유형으로 제품 카탈로그를 선택합니다.
   • 데이터 소스로 BigQuery를 선택합니다.
   • 브랜치 가져오기로 Branch 0을 선택합니다.

4. BigQuery 테이블에서 찾아보기를 클릭합니다.

5. 검색창에 products를 입력하고 검색을 클릭합니다.

6. products - 데이터 세트: merchant_center 테이블의 라디오 버튼을 선택합니다.

7. 선택을 클릭합니다.

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

소스 테이블에 id 필드가 없어 계속 진행할 수 없습니다.

데이터에 스키마로 인한 더 많은 문제가 있습니다.

9. 위로 스크롤하여 데이터 스키마로 판매자 센터를 선택합니다.

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

11. X를 클릭하여 가져오기 작업이 성공적으로 예약되었음을 안내하는 팝업을 닫습니다.

12. 취소를 클릭하여 가져오기 페이지를 닫고 소매업 데이터 페이지로 돌아가서 데이터 가져오기의 상태를 확인합니다.

BigQuery에서 소매업 스키마 데이터 가져오기

이 작업에서는 소매업 제품 스키마를 사용하는 BigQuery 테이블에서 카탈로그로 제품 데이터를 가져옵니다.

1. GCP 콘솔의 탐색 메뉴()에서 모든 제품 보기를 클릭하고 인공지능 섹션에서 상거래 검색 > 데이터를 선택하여 소매업 데이터 관리 페이지를 엽니다.

2. 카탈로그 탭이 선택되어 있는지 확인한 후 가져오기를 클릭합니다.

3. 제품 카탈로그를 가져오기 위해 다음과 같이 가져오기 파라미터를 구성합니다.

   • 가져오기 유형으로 제품 카탈로그를 선택합니다.
   • 브랜치 가져오기로 Branch 0을 선택합니다.
   • 데이터 소스로 BigQuery를 선택합니다.

4. 데이터 스키마로 소매업 제품 카탈로그 스키마를 선택합니다.

5. BigQuery 테이블에서 찾아보기를 클릭합니다.

6. 검색창에 products를 입력하고 검색을 클릭합니다.

7. products - 데이터 세트: retail 테이블의 라디오 버튼을 선택합니다.

8. 선택을 클릭합니다.

참고: 테이블 이름을 클릭하면 Data Catalog 페이지가 열리므로 소매업 제품 가져오기 페이지로 돌아가야 합니다.

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

다음과 비슷한 메시지가 있는 팝업 메시지가 표시될 때까지 기다려야 합니다.

import-products-6583047802807380211 가져오기 작업을 예약했습니다. 통합 활동 패널에 새 장기 실행 작업이 표시되는 데 최대 5분이 걸릴 수 있습니다.

가져오기 작업이 예약되면 정기적인 데이터 가져오기 작업을 예약하는 데 사용할 수 있는 gcloud scheduler 명령어의 세부정보도 표시됩니다.

10. X를 클릭하여 가져오기 작업이 성공적으로 예약되었음을 안내하는 팝업을 닫습니다.

11. 취소를 클릭하여 가져오기 페이지를 닫고 소매업 데이터 페이지로 돌아가서 카탈로그 데이터 가져오기 태스크의 상태를 확인합니다.

12. 상거래 검색 탐색 메뉴에서 데이터를 클릭한 다음 활동 상태를 클릭하여 가져오기 태스크의 진행 상황을 모니터링합니다.

제품 카탈로그 가져오기 활동 섹션에서 가져오기 태스크의 상태가 성공으로 변경되기까지 1~2분 정도 걸립니다. 총 1,268개의 항목이 가져오기되었을 것입니다.

Cloud Storage에서 사용자 이벤트 데이터 가져오기

이 작업에서는 BigQuery 테이블에서 사용자 이벤트 데이터를 가져옵니다.

1. GCP 콘솔의 탐색 메뉴()에서 모든 제품 보기를 클릭하고 인공지능 섹션에서 상거래 검색 > 데이터를 선택하여 소매업 데이터 관리 페이지를 엽니다.

2. 이벤트 탭이 선택되어 있는지 확인한 후 가져오기를 클릭합니다.

3. 제품 카탈로그를 가져오기 위해 다음과 같이 가져오기 파라미터를 구성합니다.

   • 가져오기 유형으로 사용자 이벤트를 선택합니다.
   • 데이터 소스로 Google Cloud Storage를 선택합니다.

4. Google Cloud Storage 위치에서 찾아보기 버튼을 클릭합니다.

5. 이름이 인 스토리지 버킷으로 이동하여 recent_retail_events.json 파일을 선택합니다.

6. 파일 이름을 클릭하여 선택합니다.

7. 선택을 클릭합니다.

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

9. X를 클릭하여 가져오기 작업이 성공적으로 예약되었음을 안내하는 팝업을 닫습니다.

10. 취소를 클릭하여 가져오기 페이지를 닫고 소매업 데이터 페이지로 돌아가서 이벤트 데이터 가져오기 태스크의 상태를 확인합니다.

다음과 비슷한 메시지가 있는 팝업 메시지가 표시될 때까지 기다려야 합니다.

import-products-6583047802807380211 가져오기 작업을 예약했습니다. 통합 활동 패널에 새 장기 실행 작업이 표시되는 데 최대 5분이 걸릴 수 있습니다.

가져오기 작업이 예약되면 정기적인 이벤트 가져오기 작업을 예약하는 데 사용할 수 있는 gcloud scheduler 명령어의 세부정보도 표시됩니다.

9. gcloud scheduler 명령어가 표시되고 가져오기 태스크가 예약될 때까지 기다립니다.

10. X를 클릭하여 가져오기 작업이 성공적으로 예약되었음을 안내하는 팝업을 닫습니다.

11. 취소를 클릭하여 가져오기 페이지를 닫고 소매업 데이터 페이지로 돌아가서 이벤트 데이터 가져오기 태스크의 상태를 확인합니다.

12. 상거래 검색 탐색 메뉴에서 데이터를 클릭한 다음 활동 상태를 클릭하여 가져오기 태스크의 진행 상황을 모니터링합니다.

사용자 이벤트 가져오기 활동 섹션에서 가져오기 태스크의 상태가 성공으로 변경되기까지 1~2분 정도 걸립니다. 약 32,000개의 항목이 가져오기되었고 5개의 항목이 실패했을 것입니다.

작업 3. 데이터 가져오기 이벤트 및 오류 검토하기

이 작업에서는 데이터 가져오기 작업을 검토하고 잘못된 데이터가 발견되었을 때 가져오기 태스크에서 로깅한 몇 가지 오류를 살펴봅니다.

1. 상거래 검색 탐색 메뉴에서 데이터를 클릭한 다음 활동 상태를 클릭하여 가져오기 태스크의 진행 상황을 모니터링합니다.

2. 사용자 이벤트 탭을 클릭한 다음 오류를 검토하기 위해 세부정보 열에서 전체 오류 로그 보기를 클릭합니다.

그러면 소스 데이터가 있던 Cloud Storage 버킷의 /error 폴더가 열립니다.

3. 가져온 이벤트 데이터 파일에 해당하는 파일의 이름을 클릭합니다. 크기는 약 1KB일 것입니다.

4. 다운로드를 클릭하여 파일을 다운로드한 다음 컴퓨터에서 파일을 열고 오류 세부정보를 검토합니다. 이벤트의 데이터 스키마에 각종 문제가 있어 가져오기가 실패한 5개의 이벤트를 볼 수 있을 것입니다.

{ "code": 3, "message": "'userEvent.productDetails' is required for eventType add-to-cart.", "details": [{ "@type": "type.googleapis.com/google.protobuf.Struct", "value": { "line_number": 475 } }] } { "code": 3, "message": "link: Cannot find field.", "details": [{ "@type": "type.googleapis.com/google.protobuf.Struct", "value": { "line_number": 478 } }] }

5. Cloud 콘솔로 돌아가서 Cloud Storage 탭을 닫습니다.

6. 소매업 활동 상태 탭을 열고 닫기를 클릭하여 활동 상태 팝업을 닫습니다.

작업 4. 제품 카탈로그 및 사용자 이벤트 데이터 검토하기

이 작업에서는 가져온 제품 및 이벤트 데이터를 검토합니다.

1. 상거래 검색 탐색 메뉴에서 데이터를 클릭한 다음 카탈로그 탭이 선택되어 있는지 확인합니다.

2. 분기 이름으로는 설정된 Branch 0 (기본)을 그대로 둡니다.

3. 카탈로그 제품 목록에 카탈로그로 업로드된 1,268개의 제품 레코드가 표시됩니다. 이 중에서 746개는 재고가 있습니다.

4. 필터에 GGOEGCBT136699를 입력합니다.

그러면 Google Yellow YoYo의 제품 레코드가 표시됩니다. 이 제품은 재고가 없는 것을 볼 수 있습니다.

5. 링크 아이콘을 클릭하여 링크를 열어 봅니다. 열린 페이지에 '죄송합니다. 이 페이지를 사용할 수 없습니다'가 표시됩니다.

6. 열린 제품 탭을 닫고 상거래 검색 데이터 페이지로 돌아갑니다.

7. 필터에 GGOECAEB163612를 입력합니다.

그러면 Google Black Cloud Tee의 제품 레코드가 표시됩니다. 이 제품은 재고가 있는 것을 볼 수 있습니다.

8. 링크 아이콘을 클릭하여 링크를 엽니다. Google Merchandise Store의 제품 페이지가 열립니다.

9. 열린 제품 탭을 닫고 상거래 검색 데이터 페이지로 돌아갑니다.

작업 5. Retail API를 사용하여 사용자 이벤트 데이터 업로드하기

이번에는 curl 및 그 밖의 명령줄 유틸리티로 Retail Recommendations AI API를 호출하여 요청을 수행하고, 추천을 받고, 결과를 필터링하고 상세검색하는 방법을 살펴봅니다.

요청 인증을 위한 IAM 서비스 계정 만들기

1. 프로젝트 ID를 저장할 환경 변수를 만듭니다.

   export PROJECT_ID=$(gcloud config get-value core/project)

2. Retail API에 대한 제어된 액세스를 위해 IAM 서비스 계정을 만듭니다.

   export SA_NAME="retail-service-account" gcloud iam service-accounts create $SA_NAME --display-name $SA_NAME

3. 서비스 계정을 소매업 편집자 IAM 역할에 바인딩합니다.

   gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:$SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/retail.editor"

실습 사용자 계정이 새 서비스 계정으로 가장 기능을 사용하도록 허용하기

실습 사용자를 위해 서비스 계정 토큰 생성자 역할로 서비스 계정에 대한 역할 바인딩을 만들면 실습 사용자가 서비스 계정 가장 기능을 사용하여 서비스 계정에 대해 제한된 기간의 인증 토큰을 안전하게 생성할 수 있습니다. 이 토큰은 API 및 서비스에 대한 액세스를 대화형으로 테스트하는 데 사용할 수 있습니다.

1. 사용자 계정이 가장 기능을 허용하도록 Retail API 서비스 계정에 역할 바인딩을 만듭니다.

   export USER_ACCOUNT=$(gcloud config list --format 'value(core.account)') gcloud iam service-accounts add-iam-policy-binding $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com --member "user:$USER_ACCOUNT" --role roles/iam.serviceAccountTokenCreator

2. Retail API에 대한 임시 액세스 토큰을 생성합니다.

   export ACCESS_TOKEN=$(gcloud auth print-access-token --impersonate-service-account $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com )

서비스 계정 토큰 생성자 역할이 전파되기까지 최대 10분이 소요될 수 있기 때문에 이 명령어는 실패할 수 있습니다. 이 명령어가 실패한다면 1분 후에 다시 시도해 보세요. 그래도 실패한다면 성공할 때까지 다시 시도하세요. 명령어가 가장 기능을 사용하고 있음을 알리는 경고도 표시될 것입니다. 이는 정상적인 동작입니다.

Retail API에 사용자 이벤트 제출하기

JSON 형식의 사용자 이벤트 데이터를 Retail API userEvents:write 메서드로 전달하여 샘플 사용자 이벤트를 Retail API에 업로드합니다.

1. 샘플 사용자 이벤트 JSON 데이터를 환경 변수에 저장합니다.

   DATA='{ "eventType": "detail-page-view", "visitorId": "GA1.3.1260529204.1622654859", "productDetails": [{ "product": { "id": "GGOEGDHB163199" } }, { "product": { "id": "GGOEAAKQ137410" } } ] }'

2. Retail API userEvents.write 메서드를 사용하여 사용자 이벤트 데이터를 카탈로그에 쓰기 위한 REST API URL을 환경 변수에 저장합니다.

   URL="https://retail.googleapis.com/v2/projects/${PROJECT_ID}/locations/global/catalogs/default_catalog/userEvents:write?access_token=${ACCESS_TOKEN}"

   이것은 사용자 이벤트 데이터를 Retail API에 쓰기 위한 REST API URL입니다. URL에 프로젝트 ID에 대한 환경 변수 대체와 access_token이라는 액세스 토큰 인라인 파라미터가 있는 것을 볼 수 있습니다. 이 토큰은 앞에서 가장 기능을 사용하여 생성한 서비스 계정을 사용하여 요청을 인증합니다.

3. curl을 사용하여 REST API를 통해 사용자 이벤트를 업로드합니다.

   curl -H 'Content-Type: application/json' -X POST -d "${DATA}" $URL

   curl을 사용하여 POST 요청에서 이벤트 데이터를 JSON 데이터 페이로드로 전달하는 userEvents:write 메서드를 호출했습니다.

   { "eventType": "detail-page-view", "visitorId": "GA1.3.1260529204.1622654859", "eventTime": "2021-06-28T18:39:26.691324Z", "productDetails": [ { "product": { "name": "projects/610724409905/locations/global/catalogs/default_catalog/branches/0/products/GGOEGDHB163199", "id": "GGOEGDHB163199", "type": "PRIMARY", "primaryProductId": "GGOEGDHB163199", "categories": [ "Drinkware" ], "title": "Google Chrome Dino Light Up Water Bottle", "priceInfo": { "currencyCode": "USD", "price": 24 }, "availability": "IN_STOCK", "uri": "https://shop.googlemerchandisestore.com/Google+Redesign/Google+Chrome+Dino+Light+Up+Water+Bottle", "images": [ { "uri": "https://shop.googlemerchandisestore.com/store/20160512512/assets/items/images/GGOEGDHB163199.jpg" } ] } }, { "product": { "name": "projects/610724409905/locations/global/catalogs/default_catalog/branches/0/products/GGOEAAKQ137410", "id": "GGOEAAKQ137410", "type": "PRIMARY", "primaryProductId": "GGOEAAKQ137410", "categories": [ "Apparel" ], "title": "Android Iconic Sock", "priceInfo": { "currencyCode": "USD", "price": 17 }, "availability": "IN_STOCK", "uri": "https://shop.googlemerchandisestore.com/Google+Redesign/Apparel/Android+Iconic+Sock", "images": [ { "uri": "https://shop.googlemerchandisestore.com/store/20160512512/assets/items/images/GGOEAAKQ137410.jpg" } ] } } ] }

업로드가 성공하면 응답에 제품 URL과 이미지 같은 연결된 제품 데이터와 이벤트 타임스탬프를 포함하는 형식이 적용된 데이터가 표시됩니다. 업로드가 실패하면 오류가 표시됩니다. 가장 일반적인 오류는 잘못된 형식의 페이로드, URL 또는 유효하지 않은 토큰과 관련이 있습니다.

수고하셨습니다.

다양한 기법으로 소매업 제품 카탈로그 및 사용자 이벤트 데이터를 업로드하고, 일반적인 데이터 수집 오류를 살펴보고, Cloud 콘솔과 Retail API를 사용하여 소매업 카탈로그 및 이벤트 데이터를 검토했습니다.

실습 종료하기

실습을 완료하면 실습 종료를 클릭합니다. Google Cloud Skills Boost에서 사용된 리소스를 자동으로 삭제하고 계정을 지웁니다.

실습 경험을 평가할 수 있습니다. 해당하는 별표 수를 선택하고 의견을 입력한 후 제출을 클릭합니다.

별점의 의미는 다음과 같습니다.

• 별표 1개 = 매우 불만족
• 별표 2개 = 불만족
• 별표 3개 = 중간
• 별표 4개 = 만족
• 별표 5개 = 매우 만족

의견을 제공하고 싶지 않다면 대화상자를 닫으면 됩니다.

의견이나 제안 또는 수정할 사항이 있다면 지원 탭을 사용하세요.

Copyright 2026 Google LLC All rights reserved. Google 및 Google 로고는 Google LLC의 상표입니다. 기타 모든 회사명 및 제품명은 해당 업체의 상표일 수 있습니다.