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

이 페이지에서는 과거 이벤트에서 사용자 이벤트 데이터를 일괄 가져오는 방법을 설명합니다. 미디어 추천에는 사용자 이벤트가 필요합니다. 미디어 추천을 사용하지 않는 경우 사용자 이벤트를 가져올 필요가 없습니다. 하지만 미디어 검색 앱의 경우 권장됩니다.

가져올 수 있는 사용자 이벤트 유형은 userEvents 객체의 eventType 필드를 참고하세요. 사용자 이벤트를 가져오면 추천의 품질과 검색 결과의 순위를 개선할 수 있습니다. 클릭률이 높은 검색 결과는 상단에 표시되고 클릭률이 낮은 결과는 하단에 표시됩니다. 아직 가져오지 않은 문서의 사용자 이벤트는 가져오지 않습니다.

이벤트에 userEvents.Documents에 나열된 문서가 있는 경우 Vertex AI Search는 해당 문서와 이벤트를 자동으로 조인합니다. 조인을 사용하면 Vertex AI Search가 검색 결과 또는 추천에서 클릭수 및 조회수와 같은 이벤트를 올바른 문서에 기여 분석할 수 있습니다. 일반적인 사용 사례 앱의 경우 조인이 비동기식으로 발생합니다. 즉, 일괄 가져오기가 완료된 후(일반적으로 몇 분 이내에 완료됨) 사용자 이벤트가 문서에 조인됩니다. 미디어 앱의 경우 조인이 동기식으로 이루어지므로 Vertex AI Search는 일괄 가져오기가 진행되는 동안 문서에 사용자 이벤트를 조인하기 시작합니다. 콘솔에서 조인되지 않은 이벤트 측정항목을 확인하는 방법은 집계된 사용자 이벤트 정보 보기를 참고하세요.

실시간으로 사용자 이벤트를 가져오려면 실시간 사용자 이벤트 기록을 참고하세요.

다음과 같은 방법으로 이전 이벤트를 가져올 수 있습니다.

Cloud Storage에서
BigQuery에서
로컬 JSON 데이터로

사용자 이벤트의 JSON 표현은 API 참조의 userEvents를 참고하세요.

시작하기 전에

사용자 이벤트를 가져오기 전에 다음을 실행하세요.

데이터 스토어와 앱을 만듭니다.
사용자 이벤트 요구사항은 사용자 이벤트 정보를 참고하세요.

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

미디어 앱이 있는 경우 Google Cloud 콘솔 또는 API를 사용하여 사용자 이벤트를 가져올 수 있습니다. 다른 앱 유형의 경우 API를 사용하여만 가져올 수 있습니다.

콘솔

콘솔을 사용하여 미디어 앱의 사용자 이벤트를 가져오려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.

Agent Builder
앱 페이지에서 미디어 앱을 클릭합니다.
데이터 페이지로 이동합니다.

미디어 추천 앱의 경우 요구사항 탭에 가져와야 하는 미디어 문서와 사용자 이벤트가 표시됩니다.
이벤트 탭을 클릭합니다. 이미 이벤트를 가져온 경우 이 탭에 이벤트에 관한 정보가 표시됩니다.
이벤트 가져오기를 클릭합니다.
데이터 소스로 Cloud Storage를 선택합니다.
사용자 이벤트의 Cloud Storage 위치를 입력하거나 선택합니다.
가져오기를 클릭합니다.
활동 탭에는 가져오기 상태가 표시됩니다.
가져오기 오류가 발생하면 활동 탭에서 다음을 수행합니다.
1. 세부정보 열에서 오류를 펼치고 세부정보 보기를 클릭하여 활동 로그 세부정보 창에서 자세한 내용을 확인합니다.
2. 활동 로그 세부정보 창에서 전체 오류 로그 보기를 클릭하여 로그 탐색기에서 오류를 확인합니다.

REST

Cloud Storage에서 이전 사용자 이벤트를 일괄적으로 가져오려면 다음 단계를 따르세요.

가져오기의 입력 매개변수에 대한 데이터 파일을 하나 이상 만듭니다. gcsSource 객체를 사용하여 Cloud Storage 버킷을 가리킵니다.
```
{
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}
```
- INPUT_FILE: 사용자 이벤트 데이터가 포함된 Cloud Storage의 파일입니다. 각 사용자 이벤트는 줄 바꿈 없이 한 줄로 입력해야 합니다. 사용자 이벤트의 JSON 표현은 API 참조의 userEvents를 참고하세요. 입력 파일 필드는 gs://<bucket>/<path-to-file>/ 형식이어야 합니다.
- ERROR_DIRECTORY: (선택사항) 가져오기에 대한 오류 정보를 볼 수 있는 Cloud Storage 디렉터리입니다. 예를 들면 gs://<your-gcs-bucket>/directory/import_errors입니다. Vertex AI Agent Builder가 임시 디렉터리를 자동으로 만들도록 하려면 이 필드를 비워 두는 것이 좋습니다.

userEvents:import 메서드에 POST 요청을 전송하여 데이터 파일의 이름을 지정하여 이벤트를 가져옵니다.

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 print-access-token)"" \
    --data @DATA_FILE.json \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

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

BigQuery에서 사용자 이벤트 테이블을 만들 때는 사용자 이벤트 정보에 설명된 스키마를 사용하세요.

BigQuery 액세스 권한 설정

BigQuery 데이터 세트가 데이터 스토어와 다른 프로젝트에 있는 경우 다음 단계에 따라 BigQuery에 대한 액세스를 설정합니다.

Google Cloud 콘솔에서 IAM 및 관리자 페이지를 엽니다.
사용자 이벤트를 가져올 데이터 스토어가 포함된 프로젝트를 선택합니다.
Google 제공 역할 부여 포함 체크박스를 선택합니다.
이름이 Discovery Engine Service Account인 서비스 계정을 찾습니다.
이전에 Discovery Engine으로 가져오기 작업을 시작한 적이 없다면 이 서비스 계정이 나열되지 않을 수 있습니다. 이 서비스 계정이 표시되지 않으면 가져오기 태스크로 돌아가서 가져오기를 시작합니다. 권한 오류로 인해 가져오기가 실패하면 여기로 돌아와 이 작업을 완료하세요. 디스커버리 엔진 서비스 계정이 표시됩니다.
이메일 주소와 비슷한 서비스 계정의 식별자를 복사합니다(예: service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com).
동일한 IAM 및 관리자 페이지에서 BigQuery 프로젝트로 전환하고 액세스 권한 부여를 클릭합니다.
새 주 구성원에 서비스 계정의 식별자를 입력하고 BigQuery > BigQuery 데이터 뷰어 역할을 선택합니다.
저장을 클릭합니다.

BigQuery 액세스에 관한 자세한 내용은 BigQuery 문서의 데이터 세트에 대한 액세스 제어를 참고하세요.

BigQuery에서 이벤트 가져오기

콘솔

콘솔을 사용하여 미디어 앱의 사용자 이벤트를 가져오려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.

Agent Builder
앱 페이지에서 미디어 앱을 클릭합니다.
데이터 페이지로 이동합니다.

미디어 추천 앱의 경우 요구사항 탭에 가져와야 하는 미디어 문서와 사용자 이벤트가 표시됩니다.
이벤트 탭을 클릭합니다. 이미 이벤트를 가져온 경우 이 탭에 이벤트에 관한 정보가 표시됩니다.
이벤트 가져오기를 클릭합니다.
데이터 소스로 BigQuery를 선택합니다.
사용자 이벤트의 BigQuery 경로를 입력하거나 선택합니다.
가져오기를 클릭합니다.
활동 탭에는 가져오기 상태가 표시됩니다.
가져오기 오류가 발생하면 활동 탭에서 다음을 수행합니다.
1. 세부정보 열에서 오류를 펼치고 세부정보 보기를 클릭하여 활동 로그 세부정보 창에서 자세한 내용을 확인합니다.
2. 활동 로그 세부정보 창에서 전체 오류 로그 보기를 클릭하여 로그 탐색기에서 오류를 확인합니다.

REST

Cloud Storage에서 이전 사용자 이벤트를 일괄적으로 가져오려면 다음 단계를 따르세요.

userEvents:import 메서드에 POST 요청을 보내 BigQuery 프로젝트 이름, 데이터 세트 ID, 테이블 ID를 제공하여 사용자 이벤트를 가져옵니다.

이벤트를 가져올 때 dataSchema에 user_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 print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/projects/[PROJECT_NUMBER]/locations/global/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

이전 사용자 이벤트를 로컬 JSON 데이터로 가져오기

userEvents:import 메서드 호출에 이벤트의 로컬 JSON 데이터를 포함하여 사용자 이벤트를 가져올 수 있습니다.

사용자 이벤트 데이터를 JSON 파일에 넣고 API 요청에 파일을 지정하려면 다음 안내를 따르세요.

사용자 이벤트 데이터가 포함된 JSON 파일을 만듭니다. 사용자 이벤트의 JSON 표현은 API 참고 문서의 userEvents를 참고하세요.

{
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

userEvents:import 메서드에 POST 요청을 전송하여 데이터 파일의 이름을 지정하여 이벤트를 가져옵니다.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @[JSON_FILE] \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"