시작하기 전에

Google Cloud 프로젝트 만들기

Google Cloud 콘솔의 리소스 관리 페이지에서 Google Cloud 프로젝트를 만들거나 선택합니다.

리소스 관리 페이지로 이동
Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

Retail API 설정

Retail API를 Recommendations AI와 함께 사용하려면 Retail API를 사용 설정하고 Discovery Solutions 데이터 사용 약관에 동의해야 합니다. Retail Search도 사용하는 경우 사용 설정해야 합니다. Retail Search를 사용하면 쿼리 수에 따라 추가 비용이 발생합니다. 자세한 내용은 Retail Search 요금을 참조하세요.

Retail API를 설정하려면 다음 단계를 완료하세요.

Google Cloud console의 Retail 페이지로 이동합니다.

Retail 페이지로 이동
Retail API 설정 페이지에서 API 사용 설정을 클릭합니다.
Retail API 및 Recommendations AI가 사용으로 표시되면 계속을 클릭합니다.
Discovery Solutions 데이터 사용 약관을 읽고 데이터 사용 약관에 동의하면 동의를 클릭하세요.

데이터 사용 약관에 동의하면 Google Cloud Console은 Retail API 데이터 사용 약관에 동의했음을 나타냅니다.
중요: Retail API를 사용하려는 모든 프로젝트에 대해 Discovery Solutions 데이터 사용 약관에 동의해야 합니다.
Recommendations AI에서만 프로젝트를 사용하려면 시작하기를 클릭합니다.
Recommendations AI 외에도 Retail Search를 사용 설정하려면 다음 안내를 따르세요.
1. 계속을 클릭한 다음 Retail Search 사용 설정(선택사항) 페이지에서 사용 설정을 클릭합니다.
2. 시작하기를 클릭합니다.

Google Cloud Console은 사용 설정한 Retail API 구성요소를 표시합니다. 이제 프로젝트의 초기 설정을 구성할 수 있습니다.

기존 프로젝트에 Retail API 설정

2022년 4월 4일에 데이터 사용 약관이 적용되기 전에 Google Cloud 프로젝트에서 Retail API를 설정하는 경우 Retail API를 프로젝트에 계속 사용하려면 Discovery Solutions 약관에 동의해야 합니다. 또한 필요한 경우 해당 프로젝트에 Retail Search를 사용 설정해야 합니다.

기존 프로젝트의 검색 솔루션 데이터 사용 약관에 동의하려면 다음 단계를 완료하세요.

프로젝트의 Google Cloud Console에서 Retail 페이지로 이동합니다.

Retail 페이지로 이동
데이터 사용 약관 페이지에서 Discovery Solutions 데이터 사용 약관을 읽고 약관에 동의하면 동의를 클릭합니다.

중요: 프로젝트에 대한 Retail 관리자 또는 소유자 역할이 있는 경우에만 데이터 사용 약관에 동의할 수 있습니다.
Recommendations AI에서만 프로젝트를 사용하려면 시작하기를 클릭합니다.
Recommendations AI 외에도 Retail Search를 사용 설정하려면 다음 안내를 따르세요.
1. 계속을 클릭한 다음 Retail Search 사용 설정(선택사항) 페이지에서 사용 설정을 클릭합니다.
2. 시작하기를 클릭합니다.

Retail Search 또는 Retail API 사용 중지

Retail Search 사용 중지

Retail Search를 더 이상 사용하지 않으려면 지원 티켓을 제출하여 사용 중지할 수 있습니다.

티켓을 올바른 구성요소로 설정하려면 다음 필드를 선택합니다.

카테고리: 머신러닝
구성요소: Retail 솔루션: Retail Search
하위 구성요소: 계정 관리 및 결제

지원 티켓 만들기에 대한 자세한 내용은 지원 받기를 참조하세요.

Retail API 사용 중지

Retail API는 언제든지 사용 중지하여 사용하지 않을 수 있습니다. Recommendations AI와 Retail Search가 모두 사용 중지됩니다.

Retail API를 사용 중지하려면 다음 단계를 완료하세요.

Google Cloud Console에서 Retail API 서비스 세부정보 페이지로 이동합니다.

Retail API 서비스 세부정보 페이지로 이동
API 사용 중지를 클릭합니다.
Retail API를 사용 중지할까요? 상자에서 사용 중지를 클릭합니다.

Retail API 시작하기

새 프로젝트에 Retail API를 설정하면 Google Cloud 콘솔에 Retail API 프로젝트를 구성하는 데 도움이 되는 다음 세 가지 패널이 표시됩니다.

데이터 > 카탈로그: 제품 카탈로그와 카탈로그를 가져올 수 있는 링크를 표시합니다.
데이터 > 이벤트: 사용자 이벤트 및 이전 사용자 이벤트를 가져올 수 있는 링크를 표시합니다.
제공 구성: 제공 구성 세부정보와 새 제공 구성을 만들 수 있는 링크를 포함합니다.

이러한 패널을 사용하여 데이터를 가져오고 Retail API 프로젝트의 초기 구성을 만들 수 있습니다.

제품 카탈로그 가져오기

제품 카탈로그를 가져오려면 데이터 소스에 일련의 단계를 완료하세요. 제품 카탈로그에 대한 자세한 내용은 카탈로그 정보 가져오기를 참조하세요.

판매자 센터 동기화

제품 카탈로그 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
제품 카탈로그를 선택합니다.
데이터 소스로 판매자 센터 동기화를 선택합니다.
판매자 센터 계정을 선택합니다. 계정이 표시되지 않으면 사용자 액세스를 확인합니다.
선택사항: 선택한 피드의 제품만 가져오려면 판매자 센터 피드 필터를 선택합니다.

지정하지 않으면 향후 피드를 포함하여 모든 피드의 제품을 가져옵니다.
선택사항: 특정 국가 또는 언어를 타겟팅하는 제품만 가져오려면 고급 옵션 표시를 펼치고 필터링할 판매자 센터 판매 국가 및 언어를 선택합니다.
카탈로그를 업로드할 분기를 선택합니다.
가져오기를 클릭합니다.

Cloud Storage

제품 카탈로그 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
데이터 소스로 제품 카탈로그를 선택합니다.
카탈로그를 업로드할 분기를 선택합니다.
Retail 제품 카탈로그 스키마를 스키마로 선택합니다.
데이터의 Cloud Storage 위치를 입력합니다.
Retail Search를 사용 설정하지 않은 경우 제품 수준을 선택합니다.

카탈로그를 처음으로 가져오거나 카탈로그를 삭제한 후 다시 가져오는 경우 제품 수준을 선택해야 합니다. 제품 수준 자세히 알아보기 데이터를 가져온 후에 제품 수준을 변경하려면 상당한 노력이 필요합니다.

중요: 변이로 제품 카탈로그가 수집된 프로젝트는 Retail Search를 사용 설정할 수 없습니다.
가져오기를 클릭합니다.

BigQuery

제품 카탈로그 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
제품 카탈로그를 선택합니다.
데이터 소스로 BigQuery를 선택합니다.
카탈로그를 업로드할 분기를 선택합니다.
다음 스키마 중 하나를 선택합니다.
- Retail 제품 카탈로그 스키마: Retail API 스키마
- 판매자 센터: 판매자 센터에서 일괄 가져오기에 사용되는 스키마
데이터가 있는 BigQuery 테이블을 입력합니다.
선택사항: 고급 옵션 표시에서 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.

지정하지 않으면 기본 위치가 사용됩니다. 지정하면 BigQuery 및 Cloud Storage 버킷은 같은 리전에 있어야 합니다.
Retail Search를 사용 설정하지 않고 판매자 센터 스키마를 사용하는 경우 제품 수준을 선택합니다.

처음 카탈로그를 가져오거나 카탈로그를 삭제한 후 다시 가져오는 경우 제품 수준을 선택해야 합니다. 제품 수준 자세히 알아보기 데이터를 가져온 후에 제품 수준을 변경하려면 상당한 노력이 필요합니다.

중요: 변이로 제품 카탈로그가 수집된 프로젝트는 Retail Search를 사용 설정할 수 없습니다.
가져오기를 클릭합니다.

이전 사용자 이벤트 가져오기

이전 사용자 이벤트를 가져오려면 데이터 소스에 일련의 단계를 완료하세요. 이전 사용자 이벤트에 대한 자세한 내용은 이전 사용자 이벤트 가져오기를 참조하세요.

Cloud Storage

사용자 이벤트 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
사용자 이벤트를 선택합니다.
데이터 소스로 Google Cloud Storage를 선택합니다.
스키마로 Retail 사용자 이벤트 스키마를 선택합니다.
데이터의 Cloud Storage 위치를 입력합니다.
가져오기를 클릭합니다.

BigQuery

사용자 이벤트 가져오기를 클릭하여 데이터 가져오기 패널을 엽니다.
사용자 이벤트를 선택합니다.
데이터 소스로 BigQuery를 선택합니다.
데이터 스키마를 선택합니다.

Google 애널리틱스 4 또는 Google 애널리틱스 360에서 이벤트를 가져오지 않으면 Retail 사용자 이벤트 스키마를 사용합니다.
데이터가 있는 BigQuery 테이블을 입력합니다.
선택사항: 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.
지정하지 않으면 기본 위치가 사용됩니다. 지정하면 BigQuery 및 Cloud Storage 버킷은 같은 리전에 있어야 합니다.
선택사항: 고급 옵션 표시에서 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.

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

제공 구성 만들기

제공 구성이란 검색결과 또는 추천 결과를 생성하는 데 사용되는 모델 또는 컨트롤 모음을 연결하는 제공 항목입니다.

제공 구성을 만들려면 다음 단계를 완료하세요.

제공 구성 패널에서 제공 구성 만들기를 클릭합니다.
제공 구성 만들기 페이지에서 제공 구성이 사용될 제품으로 검색을 선택합니다.
제공 구성의 이름을 입력합니다.

이름은 1,024자(영문 기준) 이하여야 하고 영숫자, 밑줄, 하이픈, 공백만 포함할 수 있습니다.
선택사항: 필요한 경우 ID를 업데이트합니다.

ID는 개발자가 제공한 이름에서 생성되며 프로젝트 전체에서 고유해야 합니다. 50자(영문 기준) 이하여야 하며 공백을 포함할 수 없습니다.
계속을 클릭합니다.
이 제공 구성에 동적 패싯 생성을 사용 설정할지 여부를 선택합니다.
검색을 최적화할 검색 컨트롤을 선택하거나 만듭니다.

컨트롤에 대한 자세한 내용은 컨트롤 만들기 및 관리를 참조하세요.

Retail 대시보드

프로젝트의 초기 구성을 완료하면 Retail 콘솔에 Retail API 프로젝트의 시스템 상태가 표시됩니다. Retail 콘솔을 사용하면 Retail 리소스를 관리하고 활동을 모니터링할 수 있습니다.

Retail Google Cloud 콘솔로 이동

Retail 콘솔에 대한 자세한 내용은 Retail 관리 콘솔을 참조하세요.

앱에 대한 인증 설정

전자상거래 사이트와 같은 앱이 Retail API에 액세스할 수 있도록 인증을 설정해야 합니다.

서비스 계정. 앱은 서비스 계정을 사용하여 Product 호출을 인증합니다. 서비스 계정을 설정하려면 아래의 서비스 계정 만들기를 참조하세요.
API 키. 앱은 userEvents.Collect 메서드 호출에 API 키를 사용합니다. 자바스크립트 픽셀 또는 Google 태그 관리자를 통해 사용자 브라우저에서 사용자 이벤트를 캡처하려는 경우에만 이 인증 방법을 설정하면 됩니다. API 키를 설정하려면 아래의 API 키 만들기를 참조하세요.

서비스 계정 만들기

Google Cloud 콘솔 사용자 인증 정보 페이지로 이동합니다.
서비스 계정을 만들 프로젝트를 선택합니다. 프로젝트가 이미 선택되어 있을 수 있습니다.
사용자 인증 정보 만들기를 클릭하고 서비스 계정을 선택합니다.

서비스 계정 만들기 페이지가 열립니다.
서비스 계정 세부정보에서 다음 필드를 작성합니다.
- 서비스 계정 이름: 서비스 계정의 표시 이름입니다.
- 서비스 계정 ID: 서비스 계정의 고유한 이름입니다. 제공된 기본 ID를 사용하거나 커스텀 ID로 바꿀 수 있습니다.
- 서비스 계정 설명: 선택사항입니다. 계정에 대한 설명입니다.
만들고 계속하기를 클릭하여 서비스 계정을 만들고 계속해서 서비스 계정에 프로젝트에 대한 액세스 권한을 부여합니다.
이 서비스 계정에 프로젝트에 대한 액세스 권한 부여에서 다음 역할을 추가합니다.
- 서비스 계정 > 서비스 계정 토큰 생성자
- 기타 > Retail 편집자
선택사항: 이 서비스 계정으로 작업을 수행해야 하는 사용자나 그룹에게 서비스 계정 액세스 권한을 부여하려면 계속을 클릭하고 사용자나 그룹의 계정 정보를 입력합니다.
완료를 클릭하여 변경사항을 저장합니다.

로컬 환경에 서비스 계정 추가

cURL 명령줄 도구를 사용하여 Retail API를 호출하려면 로컬 환경에서 서비스 계정을 사용할 수 있도록 조치해야 합니다.

서비스 계정 키 JSON 파일을 가져오려면 서비스 계정 생성 및 관리의 안내를 따르세요.

JSON 파일에는 서비스 계정의 공개 키/비공개 키가 포함됩니다. 이 JSON 파일은 서비스 계정 키의 유일한 사본입니다. 이를 안전한 곳에 보관해야 합니다.

JSON 키 파일을 앱에서 액세스할 수 있는 위치에 저장해야 합니다.

cURL은 gcloud auth application-default print-access-token 명령어를 사용하여 Google Cloud CLI를 사용하는 서비스 계정에 대한 액세스 토큰을 얻습니다. gcloud CLI를 다운로드하고 설치하려면 gcloud CLI를 참조하세요. Cloud Shell을 사용하는 경우 gcloud CLI가 이미 설치되어 있습니다.

명령어 창을 닫으면 GOOGLE_APPLICATION_CREDENTIALS 환경 변수가 유지되지 않습니다. 새 명령어 창을 열 때 변수가 서비스 계정 파일의 경로로 설정되었는지 확인하려면 초기화 셸 스크립트에 값을 설정합니다.

  export GOOGLE_APPLICATION_CREDENTIALS=path-to-service-account-json-key-file

API 키 만들기

자바스크립트 픽셀 또는 태그 관리자 태그를 사용하여 사용자의 브라우저에서 사용자 이벤트를 캡처하는 경우 API 키가 필요합니다. 사용자 이벤트를 캡처하는 방법에 대한 자세한 내용은 실시간 사용자 이벤트 기록을 참조하세요.

userEvents.Collect 메서드 호출을 위한 API 키를 만들려면 다음 단계를 완료하세요.

Google Cloud 콘솔 사용자 인증 정보 페이지로 이동합니다.
Google Cloud 콘솔 페이지 상단의 프로젝트 드롭다운에서 프로젝트를 선택합니다(프로젝트가 이미 선택되어 있을 수 있음).
사용자 인증 정보 만들기를 클릭한 후 API 키를 선택합니다. 웹사이트 애플리케이션 제한사항을 추가하지 않습니다. 일부 사용자 개인 정보 보호 설정은 리퍼러 URL을 전달하지 않는 것으로 알려져 있습니다.
- 사용자 이벤트 로깅을 호출할 때 사용할 생성된 API 키를 기록합니다.
보안 강화를 위해 Retail 서비스(https://retail.googleapis.com/*)에 대한 액세스를 제한하는 API 제한을 API 키에 추가합니다.

참고: API 키는 userEvents.Collect 메서드 인증 전용입니다. 다른 Retail API 메서드에는 서비스 계정 또는 사용자 계정을 통해 OAuth 2.0이 필요합니다. 아래 예시를 참조하세요.

Examples

서비스 계정을 사용한 인증(OAuth 2.0)

다음은 서비스 계정을 사용한 OAuth 2.0 인증의 자바 예시입니다. 자세한 내용은 인증 문서를 참조하세요. Google은 앱에서 OAuth2 인증을 구현하는 데 사용할 수 있는 7개 언어로 된 클라이언트 라이브러리를 제공합니다. HTTP/REST를 직접 구현하려면 REST 인증 안내를 따르세요.

이 예시에서 your-service-account-json-key-file은 서비스 계정의 JSON 키 파일 경로로 바꿉니다.

// Simple Java example of using Google Cloud OAuth client library.
//
// Please see here for the list of libraries in different languages:
// https://developers.google.com/identity/protocols/OAuth2#libraries
//
// The following example depends on the google api client library.
//
// Maven:
//    <dependency>
//      <groupId>com.google.api-client</groupId>
//      <artifactId>google-api-client</artifactId>
//      <version>1.22.0</version>
//    </dependency>
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.GenericJson;
import com.google.api.client.json.jackson2.JacksonFactory;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class RetailApiSample {
  public static final String CREATE_PRODUCT_URL =
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products";

  public static GoogleCredential authorize() throws Exception {
    return GoogleCredential.fromStream(new FileInputStream("your-service-account-json-key-file"))
        .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloud-platform"))
        .setExpirationTimeMilliseconds(new Long(3600 * 1000));;
  }

  // Build an example product.
  public static GenericJson getProduct() {
    GenericJson categories = new GenericJson()
        .set("categories", Arrays.asList("Electronics > Computers", "Laptops"));
    GenericJson priceInfo = new GenericJson()
        .set("currency_code", "USD")
        .set("price", 800.00)
        .set("original_price", 1000.00);

    return new GenericJson()
        .set("name", "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/[ProductName]")
        .set("title", "Sample Laptop")
        .set("description", "Indisputably the most fantastic laptop ever created.")
        .set("categories", categories)
        .set("price_info", priceInfo)
        .set("availability", "IN_STOCK")
        .set("available_quantity", 1219);
  }

  public static void main(String[] args) {
    try {
      GoogleCredential credential = RetailApiSample.authorize();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(CREATE_PRODUCT_URL),
          new JsonHttpContent(new JacksonFactory(), RetailApiSample.getProduct()));
      credential.initialize(request);
      HttpResponse response = request.execute();
      System.out.println("Response content: " + response.parseAsString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

다음 단계

Retail API를 구현하는 방법에 대한 단계별 개요는 Retail API 구현을 참조하세요.