Apigee, BigQuery ML, Cloud Spanner를 사용해 고객 구매 경향을 예측하는 스마트 API 빌드

이 튜토리얼에서는 고객 구매 가능성을 예측할 수 있는 API를 만드는 방법을 설명합니다. API를 만들려면 Apigee, BigQuery ML, Cloud Spanner를 사용합니다.

이 튜토리얼은 사용자에게 보다 맞춤화된 환경을 제공하여 옴니채널 플랫폼과 전자상거래 플랫폼을 통해 더 많은 수익을 창출하려는 API 개발자와 데이터 전문가를 대상으로 합니다. 여기서는 사용자가 BigQuery, Apigee, Google Cloud CLI, Apache Maven에 익숙하다고 가정합니다.

생성된 API는 온라인 예측을 사용하여 웹사이트에서의 사용자 행동을 기반으로 실시간 조치를 취합니다. 온라인 예측은 머신러닝(ML) 통계를 제품 카탈로그 및 기타 정보와 결합하므로 여러 채널에서 고객에게 더 나은 환경을 만드는 데 도움이 됩니다. 생성한 API의 아키텍처는 다음 다이어그램과 같습니다.

고객 구매 경향을 예측하는 API 아키텍처

이 다이어그램에서는 다음 아키텍처를 보여줍니다.

  1. 모바일 애플리케이션에서 Apigee 플랫폼에 배포된 API에 요청을 보냅니다. 이 요청은 로그인한 사용자의 제품 추천 데이터를 가져옵니다.
  2. API 프록시는 BigQuery 데이터 세트에서 사용자 ID의 제품 추천 데이터를 가져옵니다.
  3. API 프록시는 Cloud Spanner 인스턴스의 제품 기본 데이터베이스에서 데이터를 가져오는 콜아웃을 만듭니다.
  4. API 프록시는 제품 추천과 제품 기본 데이터 세트의 데이터를 집계합니다.
  5. 응답이 모바일 애플리케이션에 반환됩니다.

목표

  • BigQuery에서 고객 구매 경향 데이터 세트를 만듭니다.
  • 제품 카탈로그 데이터를 Cloud Spanner 데이터베이스로 가져옵니다.
  • Apigee API 프록시를 가져오고 배포합니다.
  • BigQuery의 고객 구매 경향 데이터를 Cloud Spanner 데이터베이스의 제품 카탈로그 및 가격 정보와 통합합니다.
  • 제품 추천의 집계 뷰를 만듭니다.

비용

이 가이드에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

  • BigQuery 및 BigQuery ML 가변 슬롯
  • Cloud Spanner
  • Apigee

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요. Google Cloud를 처음 사용하는 사용자는 무료 체험판을 사용할 수 있습니다.

시작하기 전에

  1. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

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

  3. API AI Platform Training & Prediction, BigQuery, BigQuery Reservation, BigQuery Storage, Cloud Spanner, Cloud Storage, Cloud Storage API, Dataflow, Google Cloud, Cloud Storage JSON, Service Management, Service Usage 사용 설정

    API 사용 설정

  4. 콘솔에서 Cloud Shell을 활성화합니다.

    Cloud Shell 활성화

    콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

  5. Google 계정에 역할을 부여합니다. 다음 각 IAM 역할에 대해 다음 명령어를 한 번씩 실행합니다.

    • roles/apigee.admin
    • roles/bigquery.user
    • roles/bigquery.dataViewer
    • roles/spanner.admin
    • roles/spanner.databaseAdmin
    • roles/resourcemanager.projectIamAdmin
    • roles/serviceusage.serviceUsageConsumer

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • PROJECT_ID를 프로젝트 ID로 바꿉니다.
    • EMAIL_ADDRESS를 이메일 주소로 바꿉니다.
    • ROLE을 각 개별 역할로 바꿉니다.
  6. Apigee X 계정이 아직 없으면 Apigee를 설정하여 Apigee X 인스턴스를 프로비저닝합니다. 프로비저닝에 최대 1시간이 걸릴 수 있습니다.
  7. 외부 액세스를 허용하도록 Apigee X 조직을 구성합니다.

이 튜토리얼을 마치면 만든 리소스를 삭제하여 비용이 계속 청구되지 않게 할 수 있습니다. 자세한 내용은 삭제를 참조하세요.

BigQuery ML을 사용하여 전자상거래 추천 데이터 세트 만들기

이 섹션에서는 BigQuery ML의 표준 SQL 쿼리를 사용하여 ML 모델을 만들고 BigQuery의 고객 데이터로 학습시킨 후 배포합니다. 데이터를 내보내거나 모델 학습 및 배포 파이프라인을 빌드할 필요가 없습니다. BigQuery는 필요한 모든 컴퓨팅 리소스를 처리하도록 자동 확장됩니다.

이 튜토리얼에서 만드는 ML 모델은 사용자 선호사항 데이터를 기반으로 추천 시스템을 만드는 일반적이고 효과적인 방법인 행렬 분해를 사용합니다.

이 튜토리얼에서는 BigQuery에 공개적으로 호스팅되는 Google 애널리틱스 샘플 데이터 세트를 사용합니다. 이 데이터 세트는 Google 브랜드 상품을 판매하는 실제 전자상거래 웹사이트인 Google Merchandise Store에서 난독화된 12개월(2016년 8월~2017년 8월)치의 애널리틱스 360 데이터를 제공합니다.

샘플 데이터 처리

행렬 분해를 사용할 때는 사용자 선호사항을 파악하기 위해 명시적 또는 암시적 사용자 의견을 평가합니다. 명시적 의견을 사용하려면 데이터 세트에 별표 평점(1~5)과 같은 사용자 제품 선호사항에 대한 데이터가 있어야 합니다. 명시적 의견을 사용할 수 없는 경우에는 사용자가 제품 세부정보 페이지에 머문 총 시간 확인과 같은 다른 행동 측정항목을 사용하여 고객 선호사항을 추론해야 합니다. 이 튜토리얼에서는 세션 시간 데이터를 사용하여 고객 선호사항을 추론합니다.

행렬 분해 모델을 학습시키려면 고객, 평가 대상 항목, 암시적 평가를 식별하는 열이 있는 테이블이 필요합니다. 이 섹션에서는 userid, itemId, session_duration 열이 있는 테이블을 만듭니다. session_duration 열에는 특정 항목의 제품 페이지에서의 사용자 세션 시간이 포함됩니다.

애널리틱스 샘플 데이터 세트의 데이터를 사용하여 테이블을 만들려면 다음을 수행합니다.

  1. Google Cloud Marketplace에서 애널리틱스 샘플 페이지로 이동합니다.

    애널리틱스 샘플로 이동

  2. 데이터 세트 보기를 클릭합니다. 애널리틱스 샘플 데이터 세트가 선택된 상태로 BigQuery SQL 작업공간 페이지가 열립니다.

  3. 탐색기 섹션에서 프로젝트 옆에 있는 작업 보기를 클릭하고 데이터 세트 만들기를 클릭합니다.

  4. 표시된 데이터 세트 만들기 대화상자에서 다음을 수행합니다.

    1. 데이터세트 ID 필드에 bqml를 입력합니다.
    2. 데이터 위치 목록에서 us(미국의 여러 리전)를 선택합니다.
    3. 데이터 세트 만들기를 클릭합니다.
  5. 데이터 세트로 이동을 클릭한 다음 새 쿼리 작성을 클릭합니다.

  6. 쿼리 편집기에서 다음 SQL 문을 실행하여 학습 데이터가 포함된 테이블을 만듭니다.

    CREATE OR REPLACE TABLE bqml.aggregate_web_stats AS (
      WITH
        durations AS (
          --calculate pageview durations
          SELECT
            CONCAT(fullVisitorId,'-',
                 CAST(visitNumber AS STRING),'-',
                 CAST(hitNumber AS STRING) ) AS visitorId_session_hit,
            LEAD(time, 1) OVER (
              PARTITION BY CONCAT(fullVisitorId,'-',CAST(visitNumber AS STRING))
              ORDER BY
              time ASC ) - time AS pageview_duration
          FROM
            `bigquery-public-data.google_analytics_sample.ga_sessions_2017*`,
            UNNEST(hits) AS hit
        ),
        prodview_durations AS (
          --filter for product detail pages only
         SELECT
            CONCAT(fullVisitorId,'-',CAST(visitNumber AS STRING)) AS userId,
            productSKU AS itemId,
            IFNULL(dur.pageview_duration,
             1) AS pageview_duration,
          FROM
            `bigquery-public-data.google_analytics_sample.ga_sessions_2017*` t,
            UNNEST(hits) AS hits,
            UNNEST(hits.product) AS hits_product
          JOIN
            durations dur
          ON
            CONCAT(fullVisitorId,'-',
                   CAST(visitNumber AS STRING),'-',
                   CAST(hitNumber AS STRING)) = dur.visitorId_session_hit
          WHERE
          eCommerceAction.action_type = "2"
        ),
        aggregate_web_stats AS(
          --sum pageview durations by userId, itemId
          SELECT
            userId,
            itemId,
            SUM(pageview_duration) AS session_duration
          FROM
            prodview_durations
          GROUP BY
            userId,
            itemId )
        SELECT
        *
       FROM
          aggregate_web_stats
    );
    

    bqml.aggregate_web_stats 테이블이 생성되고 학습 데이터로 채워집니다.

  7. 데이터 샘플을 확인하려면 쿼리 편집기에서 다음 SQL 문을 실행합니다.

    SELECT
    *
    FROM
      bqml.aggregate_web_stats
    LIMIT
      10;
    

출력에는 사용자가 본 항목 ID와 세션 기간이 포함된 각 사용자 ID에 대한 행이 있는 테이블이 표시됩니다. 출력은 다음과 비슷합니다.

userId itemId session_duration
1 6703373209489429228-1 GGOEAXXX0808 19523
2 868731560082458910-1 GGOEAXXX0808 8312
3 4805474958539278422-1 GGOEAXXX0808 62892
4 8353360074725418910-3 GGOEAXXX0808 4883
5 8253742246691621007-2 GGOEAXXX0808 10
6 7211254729136975568-1 GGOEAXXX0808 96090
7 66777488032155805-1 GGOEAXXX0808 3893
8 0804312527321649470-1 GGOEAXXX0808 7539
9 2965429397557124425-1 GGOEAXXX0808 21776
10 8459600677575627508-1 GGOEAXXX0808 6265

가변 슬롯 구매

BigQuery에 주문형 가격을 사용하는 경우 행렬 분해 모델을 학습시키려면 가변 슬롯을 구매한 후 예약과 할당을 만들어야 합니다. BigQuery에서 정액제를 사용하는 경우 이 섹션을 건너뛰고 모델 생성, 학습, 배포로 이동하면 됩니다.

가변 슬롯을 구매하려면 bigquery.reservations.create 권한이 포함된 IAM 역할이 있어야 합니다. 이 권한은 프로젝트 소유자에게 부여되며 BigQuery 관리자(roles/bigquery.admin) 및 BigQuery 리소스 관리자(roles/bigquery.resourceAdmin) IAM 역할에 포함됩니다.

  1. 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 용량 관리를 클릭한 후 예약을 클릭합니다.

  3. API를 사용 설정하도록 BigQuery Reservation API 페이지로 리디렉션되면 사용 설정을 클릭합니다. 그렇지 않은 경우 다음 단계로 진행합니다.

  4. 예약 탭에서 슬롯 구매를 클릭합니다.

  5. 슬롯 구매 페이지에서 다음을 수행합니다.

    1. 약정 기간 목록에서 가변을 선택합니다.
    2. 위치 목록에서 us(미국의 여러 리전)를 선택합니다.
    3. 슬롯 수 목록에서 500을 선택합니다.
    4. 다음을 클릭합니다.
    5. 구매 확인 필드에 CONFIRM을 입력한 후 구매를 클릭합니다.

  6. 슬롯 약정 보기를 클릭합니다.

    용량을 프로비저닝하도록 최대 20분 정도 기다립니다. 용량이 프로비저닝되면 슬롯 약정 상태 열에 가 표시됩니다.

  7. 예약 만들기를 클릭한 후 다음 옵션을 설정합니다.

    1. 예약 이름model을 입력합니다.
    2. 위치 목록에서 us(미국의 여러 리전)를 선택합니다.
    3. 슬롯 수500을 입력합니다.
    4. 저장을 클릭합니다. 그러면 예약 페이지로 돌아갑니다.
  8. model 예약 옆에 있는 작업 열에서 할당 만들기를 선택합니다.

  9. 조직, 폴더 또는 프로젝트 선택에서 찾아보기를 클릭합니다.

  10. 이 튜토리얼을 완료할 프로젝트의 이름을 입력하거나 목록에서 선택합니다.

  11. 선택을 클릭한 후 만들기를 클릭합니다.

모델 생성, 학습, 배포

행렬 분해 모델을 만들고 학습시키고 배포하려면 다음을 수행합니다.

  1. 콘솔 BigQuery 페이지에서 새 쿼리 작성을 클릭합니다.
  2. CREATE MODEL SQL 문을 실행합니다.

    CREATE OR REPLACE MODEL bqml.retail_recommender`
      OPTIONS(model_type='matrix_factorization',
            user_col='userId',
            item_col='itemId',
            rating_col='session_duration',
            feedback_type='implicit'
            )
      AS
      SELECT * FROM bqml.aggregate_web_stats;
    

학습이 완료되면 학습된 모델이 bqml.retail_recommender 모델로 배포됩니다.

학습된 모델을 사용하여 예측하기

이 섹션에서는 배포된 bqml.retail_recommender 모델에서 예측을 가져오기 위해 ML.RECOMMEND SQL 함수를 사용합니다.

  1. 콘솔 BigQuery 페이지에서 쿼리를 작성하고 지정된 userId의 상위 5개 추천 항목을 나타내는 예측을 가져옵니다.

    DECLARE MY_USERID STRING DEFAULT "0824461277962362623-1";
    
    SELECT
     *
    FROM
      ML.RECOMMEND(MODEL `bqml.retail_recommender`,
      (SELECT MY_USERID as userID)
                  )
    ORDER BY predicted_session_duration_confidence DESC
    LIMIT 5;
    

    출력에는 예측된 세션 시간 신뢰도(높을수록 좋음), 관련 사용자 ID, 사용자가 조회한 항목 ID의 행이 표시됩니다. 출력은 다음과 비슷합니다.

    predicted_session_duration_confidence userId itemId
    1 29011.10454702254 0824461277962362623-1 GGOEGAAX0574
    2 28212.99840462358 0824461277962362623-1 GGOEGDHQ015399
    3 28126.79442866013 0824461277962362623-1 GGOEGETR014599
    4 27303.60852083874 0824461277962362623-1 GGOEGAAX0338
    5 25692.370609851147 0824461277962362623-1 GGOEGEFR024199
  2. 모든 사용자의 상위 5개 예측을 가져오려면 다음 SQL 문을 실행합니다. 이 문은 많은 행을 생성하므로 데이터 예시를 확인할 수 있도록 출력이 테이블에 기록된 후 처음 레코드 10개가 검색됩니다.

    -- Create output table of top 5 predictions
    CREATE OR REPLACE TABLE bqml.prod_recommendations AS (
    WITH predictions AS (
        SELECT
          userId,
          ARRAY_AGG(STRUCT(itemId,
                           predicted_session_duration_confidence)
                    ORDER BY
                      predicted_session_duration_confidence DESC
                    LIMIT 5) as recommended
        FROM ML.RECOMMEND(MODEL bqml.retail_recommender)
        GROUP BY userId
    )
    SELECT
      userId,
      itemId,
      predicted_session_duration_confidence
    FROM
      predictions p,
      UNNEST(recommended)
    );
    -- Show table
    SELECT
    *
    FROM
      bqml.prod_recommendations
    ORDER BY
      userId
    LIMIT
      10;
    

    출력에는 여러 사용자 ID, 사용자가 조회한 항목 ID, 예측된 세션 시간 신뢰도가 표시됩니다. 출력은 다음과 비슷합니다.

    userId itemId predicted_session_duration_confidence
    1 000170187170673177-6 GGOEGDHQ015399 15931.156936770309
    2 000170187170673177-6 GGOEGAAX0574 20178.608474922632
    3 000170187170673177-6 GGOEGAAX0338 20247.337545389437
    4 000170187170673177-6 GGOEGETR014599 15524.355852692066
    5 000170187170673177-6 GGOEGEFR024199 16443.307099088597
    6 000338059556124978-1 GGOEGAAX0338 18143.067737280064
    7 000338059556124978-1 GGOEGAAX0279 16531.718889063464
    8 000338059556124978-1 GGOEGAAX0574 20916.672241880347
    9 000338059556124978-1 GGOEGETR014599 16155.674211782945
    10 000338059556124978-1 GGOEGEFR024199 18417.17554202264

Cloud Spanner 데이터 설정

이 튜토리얼의 다음 섹션에서는 gcloud CLIMaven을 사용합니다. Cloud Shell에서 두 도구에 대한 명령어를 실행합니다. 도구를 사용하기 위해 설치할 필요는 없습니다.

  1. Cloud Shell에서 Cloud Spanner 데이터베이스에서 데이터를 설정할 수 있는 제품 추천 API 프록시 번들과 스크립트가 포함된 제품 추천 GitHut 저장소를 클론합니다.

    git clone https://github.com/apigee/devrel/tree/main/references/product-recommendations
    cd product-recommendations-v1
    
  2. datareader 서비스 계정을 만들고 이 계정에 IAM 역할을 할당합니다. 서비스 계정은 API 프록시에서 BigQuery와 Cloud Spanner 데이터베이스의 데이터에 액세스하는 데 사용됩니다.

    gcloud iam service-accounts create datareader --display-name="Data reader for BigQuery and Spanner Demo"
    gcloud iam service-accounts list | grep datareader
    gcloud iam service-accounts create datareader --display-name="Data reader for Apigee, BigQuery, and Spanner Demo"
    gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/spanner.databaseUser" --quiet
    gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/spanner.databaseReader" --quiet
    gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/bigquery.dataViewer" --quiet
    gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/bigquery.user" --quiet
    
  3. 환경 변수를 설정합니다.

    # For ApigeeX
    export PROJECT_ID=APIGEEX_PROJECT
    export ORG=$PROJECT_ID
    export ENV=eval
    export ENVGROUP_HOSTNAME=API_DOMAIN_NAME
    export SA=datareader@$PROJECT_ID.iam.gserviceaccount.com
    
    # For Cloud Spanner
    export SPANNER_INSTANCE=product-catalog
    export SPANNER_DATABASE=product-catalog-v1
    export REGION=regional-us-east1
    

    다음을 바꿉니다.

    • APIGEEX_PROJECT: Apigee X 프로젝트의 이름입니다.
    • API_DOMAIN_NAME: Apigee X UI의 관리자 > 환경 > 그룹 페이지에서 구성한 호스트 이름입니다.
  4. 콘솔 BigQuery 페이지에서 prod_recommendations 테이블을 선택한 후 미리보기 탭을 클릭하여 결과를 봅니다.

    1. userId 값을 복사합니다.
    2. Cloud Shell에서 환경 변수를 설정합니다.

      export CUSTOMER_USERID=USER_ID
      

      USER_ID를 이전 단계에서 복사한 userId 값으로 바꿉니다.

  5. Cloud Shell에 지정된 CUSTOMER_USERID 값의 정렬된 제품 추천 결과를 표시합니다.

    bq query --nouse_legacy_sql \
        "SELECT * FROM \`$PROJECT_ID.bqml.prod_recommendations\` AS A where A.userid = \"$CUSTOMER_USERID\"" \
        ORDER BY A.predicted_session_duration_confidence DESC
    

    출력에는 개별 사용자 ID, 사용자가 조회한 항목 ID, 예측된 세션 시간 신뢰도가 표시됩니다. 출력은 다음과 비슷합니다.

    +-----------------------+----------------+--------------------------------------------+
    |        userId         |     itemId     |      predicted_session_duration_confidence |
    +-----------------------+----------------+--------------------------------------------+
    | 6929470170340317899-1 | GGOEGAAX0037   |                          40161.10446942589 |
    | 6929470170340317899-1 | GGOEYDHJ056099 |                          27642.28480729123 |
    | 6929470170340317899-1 | GGOEGAAX0351   |                         27204.111219270915 |
    | 6929470170340317899-1 | GGOEGDWC020199 |                         25863.861349754334 |
    | 6929470170340317899-1 | GGOEGAAX0318   |                         24585.509088154067 |
    +-----------------------+----------------+--------------------------------------------+
    

Cloud Spanner 데이터베이스 만들기 및 제품 카탈로그 데이터 가져오기

  1. Cloud Shell에서 지정된 리전에 Cloud Spanner 인스턴스를 만들고 제품 카탈로그 데이터베이스를 만든 후 데이터를 가져옵니다.

    ./setup_spanner.sh
    

    이 스크립트는 CUSTOMER_USERID 환경 변수를 사용하며 생성된 항목을 표시합니다.

    Cloud Spanner 제품 카탈로그에는 특정 사용자의 BigQuery 학습 단계에서 사용된 항목만 포함됩니다. 따라서 Cloud Spanner 데이터베이스에서 제품 카탈로그 데이터를 만든 후 CUSTOMER_USERID 환경 변수를 변경하는 경우 setup_spanner.sh 셸 스크립트를 다시 실행하여 데이터를 다시 채워야 합니다.

  2. Cloud Spanner 데이터베이스에서 데이터를 확인합니다.

    gcloud spanner databases execute-sql $SPANNER_DATABASE --sql='SELECT * FROM products'
    

    출력에 가격과 이미지 경로를 포함한 Spanner 제품 카탈로그의 설명 정보와 제품 ID가 표시됩니다. 출력은 다음과 비슷합니다.

    productid       name                description                price  discount  image
    GGOEGAAX0037    Aviator Sunglasses  The ultimate sunglasses    42.42  0         products_Images/sunglasses.jpg
    GGOEGAAX0318    Bamboo glass jar    Bamboo glass jar           19.99  0         products_Images/bamboo-glass-jar.jpg
    GGOEGAAX0351    Loafers             Most comfortable loafers   38.99  0         products_Images/loafers.jpg
    GGOEGDWC020199  Hair dryer          Hottest hair dryer         84.99  0         products_Images/hairdryer.jpg
    GGOEYDHJ056099  Coffee Mug          Best Coffee Mug            4.2    0         products_Images/mug.jpg
    

Apigee 프록시 배포

이 섹션에서는 Maven 명령어를 실행하여 다음 리소스를 만듭니다.

  • 이름이 product-recommendations-v1인 프록시
  • 이름이 product-recommendations-v1-$ENV인 API 제품
  • 이름이 demo@any.com인 앱 개발자 사용자
  • 이름이 product-recommendations-v1-app-$ENV인 앱

리소스를 만드는 데 Maven은 GitHub 저장소의 pom.xml 파일을 사용합니다. 이 파일에는 설치 안내와 단계가 포함되어 있습니다.

pom.xml 파일의 프로필 섹션에는 apigee.org, apigee.env, api.northbound.domain, gcp.projectid, googletoken.email, api.userid의 값이 포함되어 있습니다. 이러한 값은 프로젝트에 따라 다르며 명령줄을 통해 설정됩니다. 다음 예시에서는 값이 포함된 pom.xml 파일의 섹션을 보여줍니다.

<profile>
  <id>eval</id>
  <properties>
    <apigee.profile>eval</apigee.profile>
    <apigee.org>${apigeeOrg}</apigee.org>
    <apigee.env>${apigeeEnv}</apigee.env>
    <api.northbound.domain>${envGroupHostname}</api.northbound.domain>
    <gcp.projectid>${gcpProjectId}</gcp.projectid>
<apigee.googletoken.email>${googleTokenEmail}</apigee.googletoken.email>
    <api.userid>${customerUserId}</api.userid>
  </properties>
</profile>

이 값은 이전에 Cloud Spanner 데이터 설정 시 설정한 값입니다.

프록시를 배포하려면 다음을 수행합니다.

  • Cloud Shell에서 프록시와 관련 아티팩트를 설치한 후 API를 테스트합니다.

    mvn -P eval clean install -Dbearer=$(gcloud auth print-access-token) \
        -DapigeeOrg=$ORG \
        -DapigeeEnv=$ENV \
        -DenvGroupHostname=$ENVGROUP_HOSTNAME \
        -DgcpProjectId=$PROJECT_ID \
        -DgoogleTokenEmail=$SA \
        -DcustomerUserId=$CUSTOMER_USERID
    

    출력에 설치 단계 실행과 통합 테스트 API 호출 결과가 표시됩니다. /openapi 엔드포인트에 대한 호출 하나와 /products 엔드포인트에 대한 다른 호출이 있습니다. 테스트 결과에서는 API 프록시가 설치, 배포, 작동하는지 확인합니다. 또한 출력에는 이후 API 테스트 호출에 사용할 수 있는 앱 사용자 인증 정보가 표시됩니다.

Recommendations API 테스트

  1. Cloud Shell에서 Apigee API에 curl을 호출하여 앱의 API 키에 대한 환경 변수를 설정합니다.

    APIKEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://apigee.googleapis.com/v1/organizations/$ORG/developers/demo@any.com/apps/product-recommendations-v1-app-$ENV \
        | jq -r .credentials[0].consumerKey)
    

    APIKEY 값을 기록해 둡니다. 나중에 선택적으로 AppSheet 앱을 만들 때 이 정보가 필요합니다.

  2. API 프록시를 설치할 때 지정한 CUSTOMER_USERID 값의 결과를 가져오려면 테스트 호출을 수행합니다.

    curl -s https://$ENVGROUP_HOSTNAME/v1/recommendations/products \
    -H "x-apikey:$APIKEY" | jq
    

OpenAPI 사양(OAS)에 정의된 API를 사용하면 요청에서 다음 헤더를 지정할 수 있습니다.

  • x-apikey: 보안 스킴의 앱 고객 키입니다.
  • x-userid: 요청하는 사용자 식별자입니다. 제공되지 않으면 이 값의 기본값은 프록시에 구성된 CUSTOMER_USERID 값입니다.
  • cache-control: 응답을 캐시하는 시간입니다. 이 헤더를 사용하면 300초 동안 응답을 캐시하거나 no-cache를 지정하여 재정의할 수 있습니다.

CUSTOMER_USERID 값을 변경하거나 캐싱을 제어하려면 다음 예시 호출과 같이 헤더 값을 설정하면 됩니다.

curl -s "https://$ENVGROUP_HOSTNAME/v1/recommendations/products" \
-H "x-apikey:$APIKEY" \
-H "x-userid:$CUSTOMER_USERID" \
-H "Cache-Control:no-cache" | jq

예시 호출의 응답은 다음과 비슷합니다.

{
  "products": [
    {
      "productid": "GGOEGAAX0037",
      "name": "Aviator Sunglasses",
      "description": "The ultimate sunglasses",
      "price": "42.42",
      "image": "products_Images/sunglasses.jpg"
    },
    {
      "productid": "GGOEYDHJ056099",
      "name": "Coffee Mug",
      "description": "Best Coffee Mug",
      "price": "4.2",
      "image": "products_Images/mug.jpg"
    },
    {
      "productid": "GGOEGAAX0351",
      "name": "Loafers",
      "description": "Most comfortable loafers",
      "price": "38.99",
      "image": "products_Images/loafers.jpg"
    },
    {
      "productid": "GGOEGDWC020199",
      "name": "Hairdryer",
      "description": "Hotest hairdryer",
      "price": "84.99",
      "image": "products_Images/hairdryer.jpg"
    },
    {
      "productid": "GGOEGAAX0318",
      "name": "Bamboo glass jar",
      "description": "Bamboo glass jar",
      "price": "19.99",
      "image": "products_Images/bamboo-glass-jar.jpg"
    }
  ]
}

Apigee 정책

다음 섹션에 나열된 Apigee 정책은 이 튜토리얼의 API 프록시 번들에 사용됩니다.

Pre-flow

SpikeArrest
트래픽 일시 급증으로부터 백엔드 BiqQuery 서비스를 보호합니다.
할당량
소비자 애플리케이션과 개발자를 기반으로 API 요청을 제한합니다. 제한은 API 제품에 구성됩니다.
ResponseCache - uri
서비스에서 응답을 캐시하여 BiqQuery 데이터 웨어하우스에 대한 요청을 줄입니다.

Products-flow

AssignMessage - 쿼리 요청 생성
BigQuery 데이터 세트에서 제품 추천 목록을 가져오기 위해 SQL 쿼리를 사용하여 HTTP 요청을 설정합니다.
자바스크립트 및 ExtractVariable 정책
BigQuery 서비스에서 데이터 형식을 지정하고 더욱 사용자 친화적인 응답 메시지를 만듭니다.
LookupCache - Cloud Spanner 세션
Apigee 캐시에서 Cloud Spanner 데이터베이스 세션 ID를 조회합니다.
ServiceCallout - Cloud Spanner 세션
Apigee 캐시에 세션 ID가 없거나 ID가 만료됐으면 Cloud Spanner 서비스에 대한 요청을 수행하고 데이터베이스 세션을 만듭니다.
PopulateCache - Cloud Spanner 세션
Apigee 캐시에 Cloud Spanner 세션 ID를 채웁니다.
ServiceCallout - 제품 카탈로그 조회
Cloud Spanner 제품 카탈로그 데이터베이스에서 제품 세부정보를 가져옵니다.
자바스크립트 - 제품 데이터 형식 지정
제품 카탈로그 데이터베이스에서 데이터 형식을 지정하여 OAS를 준수하는 API 응답 메시지를 만듭니다.

OpenAPI-flow

AssignMessage - OAS JSON
API의 OAS JSON 응답을 설정합니다.

선택사항: Apigee를 데이터 소스로 사용하여 AppSheet 앱 만들기

전자상거래 웹사이트 최종 사용자와 비즈니스 사용자에게 제품 추천을 보여주려면 이 섹션처럼 AppSheet 앱을 만들면 됩니다.

AppSheet 계정 만들기

이메일 주소를 사용하여 AppSheet 계정을 만듭니다.

데이터 소스 만들기

AppSheet는 API 프록시를 새 앱의 데이터 소스로 사용합니다. 데이터 소스를 만들려면 다음을 수행합니다.

  1. AppSheet에 로그인합니다.
  2. 내 계정 페이지에서 소스 > 새 데이터 소스를 클릭합니다.
  3. 새 데이터 소스 추가 대화상자에서 프록시 product-recommendations-v1 이름을 입력한 후 Apigee를 클릭합니다.
  4. Apigee API 연결 정보 추가 대화상자에서 다음 옵션을 설정합니다.

    1. 수동을 선택합니다.
    2. Apigee API 키 필드에 프록시를 테스트하는 데 사용한 앱의 API 키를 입력합니다. API 키가 없으면 echo $APIKEY.를 실행하여 Cloud Shell로 가져옵니다.
    3. Apigee API 기본 경로 필드에 다음을 입력합니다.

      https://ENVGROUP_HOSTNAME/v1/recommendations
      

      ENVGROUP_HOSTNAME을 관리자 > 환경 > 그룹의 Apigee X UI에 구성된 호스트 이름으로 바꿉니다.

    4. API 리소스 경로 필드에 경로 서픽스 products를 입력합니다.

    5. 테스트를 클릭합니다.

    6. 테스트가 성공적으로 완료되면 액세스 승인을 클릭합니다.

액세스를 승인하면 AppSheet 콘솔에 product-recommendations-v1의 새 타일이 표시됩니다.

앱 만들기

  1. AppSheet products-template 앱 페이지로 이동합니다.
  2. 복사 및 맞춤설정을 클릭합니다. 앱 클론 대화상자가 표시됩니다.
  3. 앱 이름 필드에 프록시 이름 product-recommendations-v1을 입력한 후 앱 복사를 클릭합니다. 앱이 생성될 때까지 잠시 기다립니다.
  4. 앱 시작하기 페이지에서 앱 맞춤설정을 클릭합니다. 기본적으로 앱은 Google 시트의 샘플 데이터 소스를 사용합니다.
  5. 이전에 만든 Apigee 데이터 소스와 일치하도록 데이터 소스를 변경합니다.

    1. + 새 테이블을 클릭한 후 제품 추천 v1을 클릭합니다.
    2. 시트/테이블 선택 대화상자에서 제품을 선택합니다.
    3. 새 테이블 만들기 대화상자에서 읽기 전용을 클릭한 후 이 테이블 추가를 클릭합니다.

    앱이 제품 2 탭과 다른 데이터 뷰와 함께 표시됩니다. 새 데이터 뷰에서는 각 항목의 설명과 가격에 대한 값이 다릅니다. 항목 순서는 예측의 순서와 다릅니다.

  6. AppSheet 기본 정렬을 삭제하여 데이터 소스에서 항목이 반환되는 순서를 변경합니다.

    1. 측면 탐색 메뉴에서 UX를 선택합니다.
    2. 기본 뷰 섹션에서 제품 2를 선택합니다.
    3. 뷰 옵션 섹션의 정렬 기준 옆에 있는 이름, 오름차순 항목을 삭제합니다. 이제 AppSheet에 표시된 순서가 API 호출의 결과와 동일하며 하단에 응답의 마지막 항목이 표시되는지 관찰합니다.
  7. 앱을 저장합니다.

필요에 따라 원래 제품 테이블과 UX를 삭제하고 '제품 2' 테이블의 이름을 변경하고 '제품 추천'을 볼 수 있습니다.

삭제

이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.

프로젝트 삭제

  1. 콘솔에서 리소스 관리 페이지로 이동합니다.

    리소스 관리로 이동

  2. 프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제를 클릭합니다.
  3. 대화상자에서 프로젝트 ID를 입력한 후 종료를 클릭하여 프로젝트를 삭제합니다.

개별 리소스 삭제

반복 비용을 방지하려면 BigQuery 가변 슬롯 예약, BigQuery 데이터 세트, AI Platform 모델을 삭제합니다.

BigQuery 가변 슬롯 예약 삭제

  1. 콘솔 BigQuery 페이지에서 용량 관리를 선택한 후 예약 탭을 클릭합니다.
  2. 모델 항목을 엽니다.
  3. 예약 옆에 있는 작업 보기를 클릭한 후 삭제를 클릭합니다.
  4. 모델 항목 옆에 있는 작업 보기를 클릭한 다음 삭제를 클릭합니다.
  5. Cloud Shell에서 배포, 프록시, 연결된 아티팩트를 삭제합니다.

    mvn -P eval process-resources -Dbearer=$(gcloud auth print-access-token) \
        -DapigeeOrg=$ORG -DapigeeEnv=$ENV -Dskip.integration=true \
        apigee-config:apps apigee-config:apiproducts apigee-config:developers -Dapigee.config.options=delete \
        apigee-enterprise:deploy -Dapigee.options=clean
    
  6. Spanner 리소스를 삭제합니다.

    ./cleanup_spanner.sh
    

BigQuery 데이터 세트 삭제

  1. 콘솔 BigQuery 페이지의 리소스 섹션에서 이 튜토리얼을 완료한 프로젝트를 확장합니다.
  2. bqml 데이터 세트를 선택한 후 데이터 세트 삭제를 클릭합니다.
  3. 오버레이 창이 나타나면 bqml을 입력한 다음 삭제를 클릭합니다.

AI Platform 모델 삭제

  1. Google Cloud 콘솔에서 AI Platform 모델 페이지로 이동합니다.

    AI Platform 모델로 이동

  2. 모델 목록에서 rpm_bqml_model을 클릭합니다.

  3. 모델 세부정보 페이지에서 V_1(기본값) 버전의 체크박스를 선택합니다.

  4. 더보기를 클릭한 후 삭제를 클릭합니다.

  5. 버전 삭제가 완료되면 뒤로를 클릭하여 모델 목록으로 돌아갑니다.

  6. rpm_bqml_model 모델의 체크박스를 선택합니다.

  7. 더보기를 클릭한 후 삭제를 클릭합니다.

  8. Cloud Shell에서 서비스 계정을 삭제합니다.

    gcloud iam service-accounts delete $SA
    

다음 단계