애널리틱스에서 데이터 내보내기

Apigee Edge 문서입니다.
Apigee X 문서로 이동 정보

할당된 서비스 에이전트의 권한 설정

위에서 설명한 변경사항에 대비하여 할당된 서비스 상담사의 권한을 설정하려면 다음 단계를 따르세요.

1. 다음 명령어를 입력하여 Google Cloud 서비스 에이전트의 이름을 찾습니다.

   curl -X GET \
     "https://api.enterprise.apigee.com/v1/organizations/ORG" \
     -u email:password \
     | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

   ORG는 사용자의 조직입니다. 그러면 아래와 같이 서비스 에이전트의 이름과 값이 반환됩니다.

   "property" : [
     {
      "name" : "serviceAgent.analytics",
      "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
      },

2. Google Cloud 콘솔에서 IAM 대시보드를 엽니다.
3. Google Cloud 프로젝트를 선택합니다.
4. IAM 창 상단에서 추가를 클릭합니다.
5. 새 주 구성원 필드에 1단계에서 반환된 서비스 에이전트 value를 입력합니다. 예를 들어 1단계에 표시된 value는 service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com입니다.
6. +Add Another Role(다른 역할 추가) 버튼을 클릭하고 다음 역할을 추가합니다.
   • BigQuery 사용자
   • 스토리지 관리자
7. 저장을 클릭합니다.

Apigee 애널리틱스 데이터

데이터 내보내기 형식

분석 데이터를 다음 형식 중 하나로 내보냅니다.

• 쉼표로 구분된 값(CSV)

  기본 구분 기호는 쉼표 문자이며, 지원되는 구분 기호 문자는 쉼표(,), 파이프(|), 탭(\t)입니다. 내보내기 요청 속성 참조에 설명된 대로 csvDelimiter 속성을 사용하여 값을 구성합니다.

• JSON(줄바꿈으로 구분)

  줄바꿈 문자를 구분 기호로 사용하도록 합니다.

내보낸 데이터에는 Edge에 내장된 모든 분석 측정항목과 측정기준 및 추가하는 맞춤 분석 데이터가 포함됩니다. 내보낸 데이터에 대한 설명은 분석 측정항목, 측정기준, 필터 참조를 확인하세요.

분석 데이터를 다음 데이터 저장소로 내보낼 수 있습니다.

• Google Cloud Storage
• Google BigQuery

내보내기 프로세스 개요

다음은 분석 데이터를 내보내는 데 사용되는 프로세스를 요약한 단계입니다.

1. 데이터 내보내기를 위해 데이터 저장소를 구성합니다(Cloud Storage 또는 BigQuery). 데이터 저장소가 올바르게 구성되었는지, 그리고 데이터 저장소에 데이터를 쓰는 데 사용된 서비스 계정에 올바른 권한이 있는지 확인해야 합니다.

2. 데이터 저장소에 액세스하는 데 사용되는 사용자 인증 정보를 비롯하여 데이터를 내보내는 데이터 저장소 (Cloud Storage 또는 BigQuery)의 속성을 정의하는 데이터 저장소를 만듭니다.

   데이터 스토어를 만들 때 데이터 저장소 사용자 인증 정보를 Edge 사용자 인증 정보 보관소에 업로드하여 안전하게 저장합니다. 그러면 데이터 내보내기 메커니즘이 이러한 사용자 인증 정보를 사용하여 데이터 저장소에 데이터를 씁니다.

3. 데이터 내보내기 API를 사용하여 데이터 내보내기를 시작합니다. 데이터 내보내기는 백그라운드에서 비동기식으로 실행됩니다.

4. 데이터 내보내기 API를 사용하여 내보내기가 완료되는 시점을 확인합니다.

5. 내보내기가 완료되면 데이터 저장소에서 내보낸 데이터에 액세스합니다.

다음 섹션에서는 이러한 단계를 자세히 설명합니다.

데이터 저장소 구성

분석 데이터 내보내기 메커니즘은 Cloud Storage 또는 BigQuery에 데이터를 씁니다. 쓰기가 발생하려면 다음을 실행해야 합니다.

• Google Cloud Platform 서비스 계정을 만듭니다.
• Cloud Storage 또는 BigQuery에 액세스할 수 있도록 서비스 계정의 역할을 설정합니다.

Cloud Storage 또는 BigQuery의 서비스 계정 만들기

서비스 계정은 개별 사용자 대신 애플리케이션에 속하는 Google 계정 유형입니다. 그러면 애플리케이션이 서비스 계정을 사용하여 서비스에 액세스합니다.

서비스 계정에는 JSON 문자열로 표시되는 서비스 계정 키가 있습니다. 데이터 저장소에 대한 연결을 정의하는 Edge 데이터 스토어를 만들 때 이 키를 전달합니다. 그러면 데이터 내보내기 메커니즘이 키를 사용하여 데이터 저장소에 액세스합니다.

키와 연결된 서비스 계정은 Google Cloud Platform 프로젝트 소유자여야 하며 Google Cloud Storage 버킷에 대한 쓰기 액세스 권한이 있어야 합니다. 서비스 키를 만들고 필요한 페이로드를 다운로드하려면 Google Cloud Platform 문서의 서비스 계정 키 만들기 및 관리를 참고하세요.

예를 들어 키를 처음 다운로드하면 JSON 객체 형식이 됩니다.

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Google Cloud Storage 구성하기

Google Cloud Storage로 데이터를 내보내려면 먼저 다음 안내를 따르세요.

• Google Cloud Platform 프로젝트에서 BigQuery 및 Cloud Resource Manager API가 사용 설정되어 있는지 확인합니다. 자세한 내용은 API 사용 설정을 참고하세요. Apigee는 Cloud Storage로 내보낼 때 BigQuery API를 통해 BigQuery 내보내기 기능을 활용하고 각 내보내기 전에 Cloud Resource Manager API를 사용하여 권한을 확인합니다.

• 서비스 계정에 다음 역할이 할당되어 있는지 확인합니다.

  • BigQuery 작업 사용자
  • 스토리지 객체 생성자
  • 저장소 관리자 (데이터 저장소 구성 테스트에 설명된 대로 데이터 저장소 테스트에만 필요) 이 역할이 너무 광범위하다면 대신 기존 역할에 storage.buckets.get 권한을 추가할 수 있습니다.)

  또는 기존 역할을 수정하거나 커스텀 역할을 만들려면 다음 권한을 역할에 추가합니다.

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (데이터 스토어 구성 테스트에 설명된 대로 데이터 스토어 테스트에만 필요)

Google BigQuery 구성

Google BigQuery로 데이터를 내보내려면 먼저 다음 안내를 따르세요.

• Google Cloud Platform 프로젝트에서 BigQuery 및 Cloud Resource Manager API가 사용 설정되어 있는지 확인합니다. 자세한 내용은 API 사용 설정을 참고하세요. Apigee는 Cloud Resource Manager API를 사용하여 각 내보내기 전에 권한을 확인합니다.
• Google Cloud Platform 프로젝트에서 BigQuery API가 사용 설정되어 있는지 확인합니다. 자세한 내용은 API 사용 설정 및 중지를 참고하세요.

• 서비스 계정에 다음 역할이 할당되어 있는지 확인합니다.

  • BigQuery 작업 사용자
  • BigQuery 데이터 편집자

  기존 역할을 수정하거나 커스텀 역할을 만들려면 다음 권한을 역할에 추가합니다.

  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData

데이터 스토어 만들기

데이터 저장소는 데이터 저장소에 액세스하는 데 사용되는 사용자 인증 정보를 포함하여 내보내기 데이터 저장소 (Cloud Storage, BigQuery)에 대한 연결을 정의합니다.

Edge 사용자 인증 정보 보관소 정보

Edge는 인증 정보 보관소를 사용하여 내보내기 데이터 저장소에 액세스하는 데 사용되는 사용자 인증 정보를 안전하게 저장합니다. 서비스가 Edge 인증 정보 보관소의 사용자 인증 정보에 액세스할 수 있도록 하려면 사용자 인증 정보 소비자를 정의해야 합니다.

아래에 설명된 대로 Edge UI를 사용하여 데이터 저장소를 만들면 Edge에서 사용자 인증 정보에 액세스하는 데 사용되는 소비자를 자동으로 만듭니다.

데이터 스토어 구성 테스트

데이터 스토어를 만들 때 Edge는 사용자 인증 정보 및 데이터 저장소 구성이 유효한지 테스트하거나 검증하지 않습니다. 즉, 데이터 저장소를 만들고 첫 번째 데이터 내보내기를 실행하기 전에는 오류를 감지하지 않습니다.

또는 데이터 스토어 구성을 만들기 전에 테스트합니다. 대규모 데이터 내보내기 프로세스를 실행하는 데 시간이 오래 걸릴 수 있으므로 테스트가 유용합니다. 대량의 데이터를 다운로드하기 전에 사용자 인증 정보와 데이터 스토어 구성을 테스트하면 설정 문제를 빠르게 해결할 수 있습니다.

테스트에 성공하면 데이터 스토어를 만듭니다. 테스트에 실패하면 오류를 수정한 후 구성을 다시 테스트합니다. 테스트가 성공한 후에만 데이터 스토어를 만듭니다.

테스트 기능을 사용 설정하려면 다음을 실행해야 합니다.

• Google Cloud Platform 프로젝트에서 Cloud Resource Manager API가 사용 설정되어 있는지 확인합니다. 자세한 내용은 API 사용 설정 및 중지를 참고하세요.

데이터 스토어 만들기

UI에서 데이터 스토어를 만들려면 다음 단계를 따르세요.

1. 조직 관리자로 https://apigee.com/edge에 로그인하고 조직을 선택합니다.

   참고: 데이터 스토어를 만들려면 Edge 조직 관리자여야 합니다.

2. 왼쪽 탐색 메뉴에서 관리 > 애널리틱스 데이터 스토어를 선택합니다. 애널리틱스 데이터 스토어 페이지가 표시됩니다.

3. + Add Datastore(데이터 스토어 추가) 버튼을 선택합니다. 데이터 저장소 유형을 선택하라는 메시지가 표시됩니다.

   

4. 내보내기 데이터 대상 유형을 선택합니다.

   • Google Cloud Storage
   • Google BigQuery

   구성 페이지가 표시됩니다.

   

5. 데이터 스토어 이름을 입력합니다.

6. 데이터 저장소에 액세스하는 데 사용되는 사용자 인증 정보를 선택합니다. 사용 가능한 사용자 인증 정보의 드롭다운 목록이 표시됩니다.

   사용자 인증 정보는 데이터 저장소 유형에 따라 다릅니다. 자세한 내용은 Cloud Storage 또는 BigQuery용 서비스 계정 만들기를 참고하세요.

   • 사용자 인증 정보를 이미 업로드한 경우 드롭다운 목록에서 사용자 인증 정보를 선택합니다. 데이터 저장소 유형에 적합한 사용자 인증 정보를 선택해야 합니다.

   • 데이터 스토어에 새 사용자 인증 정보를 추가하는 경우 새로 추가를 선택합니다. 대화상자에 다음을 입력합니다.

     1. 사용자 인증 정보 이름
     2. 사용자 인증 정보 콘텐츠는 Cloud Storage 또는 BigQuery용 서비스 계정 만들기에 정의된 대로 데이터 저장소에 고유한 JSON 서비스 계정 키입니다.
     3. 만들기를 선택합니다.

7. 데이터 저장소 유형에 맞는 속성을 입력합니다.

   • Google Cloud Storage의 경우:

     속성	설명	필수 여부
     프로젝트 ID	Google Cloud Platform 프로젝트 ID입니다. Google Cloud Platform 프로젝트를 만들려면 Google Cloud Platform 문서의 프로젝트 만들기 및 관리를 참고하세요.	예
     버킷 이름	분석 데이터를 내보낼 Cloud Storage의 버킷 이름입니다. 데이터 내보내기를 수행하기 전에 버킷이 있어야 합니다. Cloud Storage 버킷을 만들려면 Google Cloud Platform 문서에서 Storage 버킷 만들기를 참고하세요.	예
     경로	Cloud Storage 버킷에 분석 데이터를 저장할 디렉터리입니다.	예

   • BigQuery의 경우:

     속성	설명	필수 여부
     프로젝트 ID	Google Cloud Platform 프로젝트 ID입니다. Google Cloud Platform 프로젝트를 만들려면 Google Cloud Platform 문서의 프로젝트 만들기 및 관리를 참고하세요.	예
     데이터 세트 이름	분석 데이터를 내보낼 BigQuery 데이터 세트의 이름입니다. 데이터 내보내기를 요청하기 전에 데이터 세트가 만들어졌는지 확인합니다. BigQuery 데이터 세트를 만들려면 Google Cloud Platform 문서의 데이터 세트 만들기 및 사용을 참고하세요.	예
     테이블 접두사	BigQuery 데이터 세트에서 분석 데이터에 대해 생성된 테이블 이름의 접두사입니다.	예

8. 연결 테스트를 선택하여 사용자 인증 정보를 사용하여 데이터 저장소에 액세스할 수 있는지 확인합니다.

   테스트에 성공하면 데이터 스토어를 저장합니다.

   테스트에 실패하면 문제를 해결하고 테스트를 다시 시도합니다. UI의 오류 메시지 위로 마우스를 가져가면 툴팁에 추가 정보가 표시됩니다.

9. 연결 테스트가 통과하면 데이터 스토어를 저장합니다.

데이터 스토어 수정

데이터 스토어를 수정하려면 다음 단계를 따르세요.

1. 조직 관리자로 https://apigee.com/edge에 로그인하고 조직을 선택합니다.

2. 왼쪽 탐색 메뉴에서 관리 > 애널리틱스 데이터 스토어를 선택합니다. 애널리틱스 데이터 스토어 페이지가 표시됩니다.

3. 수정하려는 보고서의 수정됨 열 위로 마우스 포인터를 가져갑니다. 수정 및 삭제 아이콘이 나타납니다.

4. 데이터 스토어를 수정하거나 삭제합니다.

5. 데이터 스토어를 수정한 경우 연결 테스트를 선택하여 사용자 인증 정보를 사용하여 데이터 스토어에 액세스할 수 있는지 확인합니다.

   테스트에 성공하면 데이터 저장소에서 샘플 데이터를 볼 수 있습니다.

   테스트에 실패하면 문제를 해결하고 테스트를 다시 시도합니다.

6. 연결 테스트가 통과하면 데이터 저장소를 업데이트합니다.

분석 데이터 내보내기

분석 데이터를 내보내려면 /analytics/exports API에 POST 요청을 실행합니다. 요청 본문에 다음 정보를 전달합니다.

• 내보내기 요청의 이름 및 설명
• 내보낸 데이터의 기간(값은 하루만 가능)
• 내보낸 데이터의 형식
• 데이터 스토어 이름
• 조직의 수익 창출 사용 설정 여부

내보내기 요청의 예시는 다음과 같습니다. 요청 본문 속성에 대한 자세한 설명은 내보내기 요청 속성 참조를 확인하세요.

POST의 응답은 다음과 같은 형식입니다.

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

응답의 state 속성은 enqueued로 설정됩니다. POST 요청은 비동기식으로 작동합니다. 즉, 요청이 응답을 반환한 후에도 백그라운드에서 계속 실행됩니다. 가능한 state 값은 enqueued, running, completed, failed입니다.

self 속성에 반환된 URL을 사용하여 애널리틱스 내보내기 요청 상태 보기에 설명된 대로 데이터 내보내기 요청의 상태를 확인합니다. 요청이 완료되면 응답의 state 속성 값이 completed로 설정됩니다. 그런 다음 데이터 저장소의 분석 데이터에 액세스할 수 있습니다.

예시1: Cloud Storage로 데이터 내보내기

다음 요청은 myorg 조직의 test 환경에서 지난 24시간의 전체 원시 데이터 세트를 내보냅니다. 콘텐츠는 JSON의 Cloud Storage로 내보내집니다.

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

self 속성으로 지정된 URI를 사용하여 애널리틱스 내보내기 요청 상태 보기에 설명된 대로 작업 상태를 모니터링합니다.

예시2: BigQuery로 데이터 내보내기

다음 요청은 쉼표로 구분된 CSV 파일을 BigQuery로 내보냅니다.

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

참고: 내보낸 CSV 파일은 다음 프리픽스로 BigQuery 테이블을 만듭니다.

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

self 속성으로 지정된 URI를 사용하여 애널리틱스 내보내기 요청 상태 보기에 설명된 대로 작업 상태를 모니터링합니다.

예시3: 수익 창출 데이터 내보내기

조직의 환경에서 수익 창출이 사용 설정된 경우 다음 두 가지 유형의 데이터 내보내기를 수행할 수 있습니다.

• 앞의 두 가지 예시와 같은 표준 데이터 내보내기
• 수익 창출 관련 데이터를 내보내는 수익 창출 데이터 내보내기

수익 창출 데이터 내보내기를 수행하려면 요청 페이로드에 "dataset":"mint"를 지정합니다. 이 옵션을 설정하려면 조직 및 환경이 수익 창출을 지원해야 합니다. 그렇지 않으면 페이로드에서 dataset 속성을 생략합니다.

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

내보내기 API 할당량 정보

Edge는 고비용 데이터 내보내기 API 호출의 과도한 사용을 방지하기 위해 /analytics/exports API 호출에 할당량을 적용합니다.

• 수익 창출이 사용 설정되지 않은 조직 및 환경의 경우 할당량은 다음과 같습니다.

  • 조직/환경당 월별 70회 호출

  예를 들어 조직에 prod 및 test라는 두 가지 환경이 있는 경우 각 환경에 대해 매달 70회의 API 호출을 수행할 수 있습니다.

• 수익 창출이 사용 설정된 조직 및 환경의 경우 할당량은 다음과 같습니다.

  • 표준 데이터의 경우 각 조직 및 환경당 월별 70회 호출
  • 수익 창출 데이터의 경우 각 조직 및 환경당 월별 70회 호출

  예를 들어 prod 조직에서 수익 창출을 사용 설정하면 표준 데이터의 경우 API 호출 70회 및 수익 창출 데이터의 경우 추가적인 API 호출 70회를 수행할 수 있습니다.

호출 할당량을 초과하면 API는 HTTP 429 응답을 반환합니다.

모든 애널리틱스 내보내기 요청 상태 보기

모든 애널리틱스 내보내기 요청의 상태를 보려면 /analytics/exports에 GET 요청을 실행합니다.

예를 들어 다음 요청은 myorg 조직의 test 환경에 대한 모든 애널리틱스 내보내기 요청 상태를 반환합니다.

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

다음은 큐에 추가된(생성되고 큐에 있는) 요청과 완료된 요청의 두 가지 내보내기 요청을 보여주는 응답 예시를 보여줍니다.

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

애널리틱스 내보내기 요청 상태 보기

특정 애널리틱스 내보내기 요청의 상태를 보려면 /analytics/exports/{exportId}에 GET 요청을 실행합니다. 여기서 {exportId}는 애널리틱스 내보내기 요청과 연결된 ID입니다.

예를 들어 다음 요청은 ID가 4d6d94ad-a33b-4572-8dba-8677c9c4bd98인 애널리틱스 내보내기 요청의 상태를 반환합니다.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

다음은 응답의 예시입니다.

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

애널리틱스 내보내기에서 분석 데이터가 반환되지 않는 경우 executionTime은 '0초'로 설정됩니다.

내보내기 요청 속성 참조

다음 표에서는 분석 데이터를 내보낼 때 JSON 형식으로 요청 본문을 전달할 수 있는 속성을 설명합니다.

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

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

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }