베타 버전에서 Retail API로 마이그레이션

이제 Recommendations에서 Retail API를 사용합니다. 이 페이지에서는 Recommendations Engine API의 v1beta1 버전(서비스 엔드포인트 https://recommendationengine.googleapis.com)에서 일반 안정화 버전의 Retail API(서비스 엔드포인트 https://retail.googleapis.com)로 이동할 경우에 도입된 변경사항과 마이그레이션 권장사항을 설명합니다.

Recommendations Engine API와 관련 문서 집합은 계속 사용 가능하지만 더 이상 업데이트되지 않습니다.

이 문서는 베타 버전의 Recommendations를 사용하기 시작한 경우에만 적용됩니다.

권장사항

  • 완전히 마이그레이션되기 전에 유효성 검사 전용 트래픽을 보냅니다.
  • 점진적 트래픽 마이그레이션이 한 번에 전환하는 것보다 좋습니다. 가능하면 트래픽을 v1beta1에서 v2로 점진적으로 마이그레이션합니다.
  • 다른 리전에서 서비스가 실행 중인 경우 전역 중단을 방지하려면 리전을 하나씩 마이그레이션하는 것이 좋습니다.

문서 변경사항

Retail 콘솔로 전환한 후에는 https://cloud.google.com/retail/docs에 있는 Retail 문서를 독점적으로 사용하는 것이 좋습니다.

Recommendation Engine API에 대한 베타 문서 세트가 계속 사용 가능하지만 더 이상 업데이트되지 않습니다.

콘솔 변경사항

Retail 콘솔은 추천 콘솔을 대체합니다.

Retail Google Cloud 콘솔은 2022년 1월 20일부터 일반에 공개됩니다. Recommendations 콘솔을 사용하는 경우 Retail 콘솔에서 Recommendations 프로젝트에 액세스하는 것이 좋습니다.

Retail 콘솔의 기능 및 용어와 추천 콘솔의 변경사항을 비교하려면 Retail 콘솔로 전환을 참조하세요.

카탈로그 및 사용자 이벤트 스키마

Retail API에서 카탈로그 및 사용자 이벤트의 스키마가 변경되었습니다.

제공 구성 및 게재위치

Retail API는 Recommendations Engine API에서 사용하는 개재위치 개념을 대체하는 제공 구성을 도입합니다.

서빙 구성은 Retail API를 사용하여 Recommendations v2 및 Retail Search v2alpha부터 사용할 수 있습니다.

servingConfig 리소스는 Retail API 버전 v2beta 및 v2alpha에서 사용할 수 있습니다. 이 리소스를 사용하여 서빙 구성을 생성, 확인, 수정, 삭제할 수 있습니다.

기존 게재위치가 있거나 새 게재위치를 만들면 Retail API가 각 게재위치와 연결된 서빙 구성을 자동으로 만듭니다. 서빙 구성을 만들어도 해당 게재위치가 생성되지 않습니다.

서빙 구성을 삭제하면 해당 게재위치가 삭제되고 해당 배치가 삭제됩니다.

서빙 구성을 사용하면 다각화 및 가격 재순위 옵션을 수정하고 거의 실시간으로 적용할 수 있습니다. 게재위치의 경우 게재위치가 가리키는 추천 모델에서만 다각화 및 가격 책정 설정을 변경할 수 있습니다.

게재위치는 계속 지원되지만 대신 제공 구성을 사용하는 것이 좋습니다.

서빙 구성에 대한 자세한 내용은 서빙 구성 및 서빙 구성 만들기를 참조하세요.

REST 및 RPC 경로

REST 및 RPC 경로에 대한 변경사항은 많이 있습니다. Retail API의 API 문서를 검토하여 Retail API를 올바르게 호출하는지 확인합니다.

이제 모든 경로에 recommendationengine.googleapis.com 대신 retail.googleapis.com이 사용됩니다.

예를 들면 다음과 같습니다.

v1beta1 Recommendations Engine API: 

GET https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

v2 Retail API:

GET https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

일부 리소스와 메서드가 이름 변경, 삭제 또는 새롭게 추가되었습니다. 아래 표에서는 v1beta1 리소스와 v2 리소스를 관련 메서드를 나란히 비교합니다.

예를 들어 v1beta1 리소스 catalogs.catalogItems는 v2 리소스 catalogs.branches.products와 동일합니다. catalogs.catalogItems에서 v1beta1에 사용할 수 있었던 list 메서드는 v2의 catalogs.branches.products에 사용할 수 없으므로 삭제됨으로 표시됩니다.

v1beta1 리소스 링크를 클릭하면 v1beta1용 API 문서로 이동합니다.

v1beta1 리소스 메서드 v2 리소스 메서드
catalogs list catalogs list
patch patch
N/A catalogs.branches.operations get
catalogs.catalogItems create catalogs.branches.products create
delete delete
get get
import import
list 삭제됨
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get 삭제됨
list
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create 삭제됨
delete
list
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list 삭제됨
purge purge
rejoin rejoin
write write
N/A operations get
list

IAM 변경사항

Retail Identity and Access Management(IAM) 역할 및 권한에 다음 변경사항이 도입되었습니다.

  • Retail은 Recommendations Engine v1beta1에서 사용한 automlrecommendations 네임스페이스 대신 retail 네임스페이스의 IAM 역할과 권한을 사용합니다.
  • Admin Viewer 역할이 삭제되었습니다.
  • predict 메서드에 더 이상 자체 API 키가 필요하지 않으므로 apiKeys에 대한 권한이 삭제되었습니다.