이 문서는 Recommendations AI, Retail Search, 새로운 Retail 콘솔에 대한 문서입니다.

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

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

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

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

먼저

Cloud Storage에서 이벤트 가져오기 튜토리얼

이 튜토리얼에서는 Cloud Storage에서 사용자 이벤트를 가져오는 방법을 설명합니다.


Cloud Shell 편집기에서 직접 이 태스크를 수행하는 방법에 대한 단계별 안내를 보려면 둘러보기를 클릭하세요.

둘러보기


다음 섹션에서는 둘러보기를 클릭할 때와 동일한 단계를 수행합니다.

BigQuery에서 이벤트 가져오기 튜토리얼

이 튜토리얼에서는 BigQuery에서 사용자 이벤트를 가져오는 방법을 보여줍니다.


Cloud Shell 편집기에서 직접 이 태스크를 수행하는 방법에 대한 단계별 안내를 보려면 둘러보기를 클릭하세요.

둘러보기


다음 섹션에서는 둘러보기를 클릭할 때와 동일한 단계를 수행합니다.

이벤트 인라인 가져오기 튜토리얼

이 튜토리얼에서는 사용자 이벤트 데이터를 인라인으로 가져오는 방법을 보여줍니다.


Cloud Shell 편집기에서 직접 이 태스크를 수행하는 방법에 대한 단계별 안내를 보려면 둘러보기를 클릭하세요.

둘러보기


다음 섹션에서는 둘러보기를 클릭할 때와 동일한 단계를 수행합니다.

시작하기 전에

가져오기 오류를 방지하고 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 애널리틱스 360의 기존 데이터를 Retail로 가져옵니다.
사용 시기 Google 애널리틱스 360이 있고 추천 또는 검색을 위한 전환을 추적하는 경우입니다. 추가 스키마 매핑은 필요하지 않습니다.
제한사항 속성의 하위 집합만 사용 가능하므로 일부 고급 Retail 기능을 사용할 수 없습니다. Retail Search를 사용하려면 Google 애널리틱스에서 노출을 추적해야 합니다.
Google 애널리틱스 4를 사용하는 BigQuery(비공개 미리보기) 설명 Google 애널리틱스 4의 기존 데이터를 Retail로 가져옵니다.
사용 시기 Google 애널리틱스 4가 있고 추천 또는 검색을 위한 전환을 추적하는 경우입니다. 추가 스키마 매핑은 필요하지 않습니다.
제한사항 속성의 하위 집합만 사용 가능하므로 일부 고급 Retail 기능을 사용할 수 없습니다. Retail Search를 사용하려면 추적을 위한 이벤트 매개변수 키-값 쌍을 설정해야 합니다. 권장 키는 search_query입니다.
인라인 가져오기 설명 userEvents.import 메서드 호출을 사용하여 가져옵니다.
사용 시기 백엔드에서 모든 인증을 수행하고 백엔드 가져오기를 수행할 수 있는 개인정보 보호를 강화하려는 경우.
제한사항 일반적으로 웹 가져오기보다 더 복잡합니다.

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

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

Console

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

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

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. 데이터 소스로 BigQuery를 선택합니다.
  5. 스키마로 Retail 사용자 이벤트 스키마를 선택합니다.
  6. 데이터가 있는 BigQuery 테이블을 입력합니다.
  7. (선택사항) 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.
    지정하지 않으면 기본 위치가 사용됩니다. 지정하면 BigQuery 및 Cloud Storage 버킷은 같은 리전에 있어야 합니다.
  8. (선택사항) 고급 옵션 표시에서 프로젝트의 Cloud Storage 버킷 위치를 데이터의 임시 위치로 입력합니다.

    지정하지 않으면 기본 위치가 사용됩니다. 지정하면 BigQuery 및 Cloud Storage 버킷은 같은 리전에 있어야 합니다.
  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",
   }

BigQuery를 사용하여 Google 애널리틱스 4 사용자 이벤트 가져오기(비공개 미리보기)

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

시작하기 전에

시작하기 전에 다음 사항을 확인하세요.

액세스 요청

이 비공개 미리보기 기능에 액세스하려면 다음 권한이 필요합니다.

  1. Retail 지원팀에 문의하여 Google 애널리틱스 4 사용자 이벤트 가져오기에 대한 권한 및 안내를 요청합니다.

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

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에서 이전 제품 정보를 활용하여 사용자 이벤트를 강화하여 모델 정확성을 높일 수 있기 때문에 이전 카탈로그 데이터는 유용할 수 있습니다.

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

다음 단계