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

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

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

이 페이지에서는 과거 이벤트에서 사용자 이벤트 데이터를 일괄 가져오는 방법을 설명합니다. Retail API 모델에는 학습을 위한 사용자 이벤트 데이터가 필요합니다.

실시간 이벤트 기록을 설정한 후 모델을 학습시키는 데 충분한 사용자 이벤트 데이터를 기록하기까지 상당한 시간이 걸릴 수 있습니다. 이전 이벤트에서 사용자 이벤트 데이터를 일괄적으로 가져와 초기 모델 학습을 가속화할 수 있습니다. 시작하기 전에 이 페이지의 사용자 이벤트 기록 권장사항시작하기 전에 섹션을 검토하세요.

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

다음이 가능합니다.

시작하기 전에

가져오기 오류를 방지하고 Retail API에 좋은 결과를 생성하는 데 충분한 데이터가 있도록 하려면 사용자 이벤트를 가져오기 전에 다음 정보를 검토합니다.

이벤트 가져오기 고려사항

이 섹션에서는 이전 사용자 이벤트의 일괄 가져오기에 사용할 수 있는 메서드, 각 메서드 사용 시기, 일부 제한사항에 대해 설명합니다.

Cloud Storage 설명 Cloud Storage 버킷에 로드된 파일에서 JSON 형식으로 데이터를 가져옵니다. 각 파일은 2GB 이하여야 하고 한 번에 최대 100개까지 파일을 가져올 수 있습니다. 가져오기는 Cloud Console 또는 cURL을 사용하여 수행될 수 있습니다. 커스텀 속성을 허용하는 Product JSON 데이터 형식을 사용합니다.
사용 시기 단일 단계로 많은 양의 데이터를 로드해야 하는 경우
제한사항 Google 애널리틱스 또는 판매자 센터에 있는 데이터는 BigQuery로만 내보낼 수 있으며 Cloud Storage로 가져오는 추가 단계가 필요합니다.
BigQuery 설명 Retail 스키마를 사용하는 이전에 로드된 BigQuery 테이블에서 데이터를 가져옵니다. Cloud Console 또는 cURL을 사용하여 수행될 수 있습니다.
사용 시기 가져오기 전에 분석 또는 사전 처리 이벤트 데이터도 사용하는 경우.
제한사항 Retail 스키마에 매핑되는 BigQuery 테이블을 만드는 추가 단계가 필요합니다. 사용자 이벤트가 많은 경우 BigQuery가 Cloud Storage보다 비용이 많이 드는 리소스라는 점을 고려하세요.
Google 애널리틱스 360을 사용한 BigQuery 설명 Google 애널리틱스의 기존 데이터를 Retail로 가져옵니다.
사용 시기 Google 애널리틱스가 있고 권장사항 또는 검색을 위해 전환을 추적하는 경우 추가 스키마 매핑은 필요하지 않습니다.
제한사항 속성의 하위 집합만 사용 가능하므로 일부 고급 Retail 기능을 사용할 수 없습니다. Retail Search를 사용하려면 Google 애널리틱스에서 노출을 추적해야 합니다.
인라인 가져오기 설명 userEvents.import 메서드 호출을 사용하여 가져옵니다.
사용 시기 백엔드에서 모든 인증을 수행하고 백엔드 가져오기를 수행할 수 있는 개인정보 보호를 강화하려는 경우.
제한사항 일반적으로 웹 가져오기보다 더 복잡합니다.

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

Cloud Console 또는 userEvents.import 메서드를 사용하여 Cloud Storage에서 사용자 이벤트를 가져옵니다.

Console

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

    데이터 페이지로 이동

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

  3. 사용자 이벤트를 선택합니다.

  4. 이벤트를 업로드할 분기를 선택합니다.

  5. 데이터 소스로 Cloud Storage를 선택합니다.

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

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

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

  8. (선택사항) 사용자 이벤트의 반복 업로드를 예약할지 선택합니다.

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

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

cURL

userEvents.import 메서드를 사용하여 사용자 이벤트를 가져옵니다.

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

    파일은 여러 개 제공하거나 하나만 제공할 수 있습니다.

    • 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"}
    }
    
  2. userEvents:import REST 메서드에 POST 요청을 하고 데이터 파일의 이름을 제공하여 Retail API로 카탈로그 정보를 가져옵니다.

    export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
    
    curl -X POST \
         -v \
         -H "Content-Type: application/json; charset=utf-8" \
         -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
         --data @./DATA_FILE.json \
      "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:import"
      }
    }'
    

BigQuery에서 사용자 이벤트 가져오기

Cloud Console 또는 userEvents.import 메서드를 사용하여 BigQuery에서 사용자 이벤트를 가져옵니다.

Console

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

    데이터 페이지로 이동

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

  3. 사용자 이벤트를 선택합니다.

  4. 이벤트를 업로드할 분기를 선택합니다.

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

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

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

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

  8. (선택사항) 사용자 이벤트의 반복 업로드를 예약할지 선택합니다.

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

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

cURL

userEvents.import 메서드를 사용하여 사용자 이벤트를 가져옵니다.

이벤트를 가져올 때 dataSchemauser_event 값을 사용합니다.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

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

BigQuery 데이터 세트가 Retail API 프로젝트와 다른 프로젝트에 속하는 경우 BigQuery 데이터 세트에 대한 액세스 권한 설정의 안내에 따라 Retail 서비스 계정에 BigQuery 프로젝트에 대한 BigQuery 데이터 편집자 역할을 부여합니다. 가져오기 요청을 수정하여 BigQuery 프로젝트 ID를 지정합니다.

"bigQuerySource": {
     "projectId": "BQ_PROJECT_ID",
   }

BigQuery에서 Google 애널리틱스 360 사용자 이벤트 가져오기

Google 애널리틱스 360과 BigQuery를 통합하고 향상된 전자상거래를 사용하는 경우 Google 애널리틱스 360 사용자 이벤트를 가져올 수 있습니다.

다음 절차에서는 사용자가 BigQuery 및 Google 애널리틱스 360을 사용하는 데 익숙하다고 가정합니다.

시작하기 전에

데이터 소스 확인

  1. 액세스 권한이 있는 BigQuery 테이블에서 가져올 사용자 이벤트 데이터 형식이 올바른지 확인합니다.

    테이블 형식은 project_id:ga360_export_dataset.ga_sessions_YYYYMMDD여야 합니다.

    테이블 형식에 대한 자세한 내용은 Google 애널리틱스 문서를 참조하세요.

  2. BigQuery Google Cloud Console에서 탐색기의 패널에서 테이블을 선택하여 테이블을 미리보기하세요.

    다음 사항을 확인합니다.

    1. clientId 열에 유효한 값이 있습니다(예: 123456789.123456789).

      이 값은 전체 _ga 쿠키 값(GA1.3.123456789.123456789와 같은 형식)과 다릅니다.

    2. hits.transaction.currencyCode 열에 유효한 통화 코드가 있습니다.

    3. search 이벤트를 가져오려는 경우 hits.page.searchKeyword 또는 hits.customVariable.searchQuery 열이 있는지 확인합니다.

      search 이벤트 가져오기는 지원되지만 애널리틱스 360은 기본적으로 search 이벤트 유형을 지원하지 않으므로 다른 이벤트 유형과 동일한 방식으로 애널리틱스 360에서 매핑되지 않습니다. 가져오는 동안 Retail API는 검색어 정보와 제품 노출의 정보(있는 경우)를 결합하여 애널리틱스 360에서 search 이벤트를 생성합니다.

      검색어는 hits.page.searchKeyword에서 또는 hits.customVariables.customVarNamesearchQuery인 경우 hits.customVariables.customVarValue에서 파생됩니다. hits.product.isImpressionsTRUE이면 제품 노출은 hits.product에서 가져옵니다.

  3. 업로드된 카탈로그와 애널리틱스 360 사용자 이벤트 테이블의 항목 ID 일관성을 확인합니다.

    BigQuery 테이블 미리보기의 hits.product.productSKU 열에 있는 제품 ID를 사용하여 product.get 메서드를 통해 동일한 제품이 업로드된 카탈로그에 있는지 확인합니다.

    export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
    
       curl \
         -v \
         -X GET \
         -H "Content-Type: application/json; charset=utf-8" \
         -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
         "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"
    

Google 애널리틱스 360 이벤트 가져오기

userEvents.import 메서드 호출 이벤트에 관한 데이터를 포함하여 사용자 이벤트를 가져옵니다.

dataSchema에는 user_event_ga360 값을 사용합니다.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:import" \
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

자바

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

BigQuery 데이터 세트가 Retail 프로젝트와 다른 프로젝트에 속하는 경우 BigQuery 데이터 세트에 대한 액세스 권한 설정의 안내에 따라 Retail 서비스 계정에 BigQuery 프로젝트에 대한 BigQuery 데이터 편집자 역할을 부여합니다. 가져오기 요청을 수정하여 BigQuery 프로젝트 ID를 지정합니다.

"bigQuerySource": {
     "projectId": "GA360_BQ_PROJECT_ID",
   }

사용자 이벤트 인라인 가져오기

curl

userEvents.import 메서드 호출에 이벤트의 데이터를 포함하여 사용자 이벤트 인라인을 가져옵니다.

가장 쉬운 방법은 사용자 이벤트 데이터를 JSON 파일에 넣고 파일을 cURL에 제공하는 것입니다.

사용자 이벤트 유형의 형식은 사용자 이벤트를 참조하세요.

  1. JSON 파일을 만듭니다.

    {
    "inputConfig": {
      "userEventInlineSource": {
          "userEvents": [
            {
              <userEvent1>>
            },
            {
              <userEvent2>
            },
            ....
          ]
        }
      }
    }
    
  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_ID]/locations/global/catalogs/default_catalog/userEvents:import"
    

자바

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

이전 카탈로그 데이터

이전 사용자 이벤트에 표시되는 이전 카탈로그 데이터를 가져올 수도 있습니다. 이 이전 카탈로그 데이터는 Retail API가 이전 제품 정보를 활용해 사용자 이벤트를 강화하여 모델 정확성을 높일 수 있기 때문에 유용할 수 있습니다.

자세한 내용은 이전 카탈로그 데이터 가져오기를 참조하세요.

다음 단계