Как экспортировать данные из Аналитики

Вы просматриваете документацию по 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. Откройте панель управления IAM в консоли Google Cloud.
3. Выберите проект Google Cloud.
4. В верхней части панели IAM нажмите Добавить.
5. В поле Новые субъекты введите сервисного агента value, полученного на шаге 1. Например, value, показанный на шаге 1, – это service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Нажмите кнопку + Добавить другую роль и добавьте следующие роли:
   • Пользователь BigQuery
   • Администратор хранилища
7. Нажмите Сохранить.

Данные Apigee Analytics

Формат экспорта данных

Экспортируйте данные аналитики в одном из следующих форматов:

• 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 включены API BigQuery и Cloud Resource Manager. Инструкции приведены в разделе Как включить API. Apigee использует BigQuery API, чтобы задействовать функции экспорта BigQuery при экспорте в Cloud Storage, и Cloud Resource Manager API, чтобы проверять разрешения перед каждым экспортом.

• Убедитесь, что сервисному аккаунту назначены следующие роли:

  • Пользователь заданий BigQuery
  • Создатель объектов в хранилище
  • Администратор хранилища (требуется только для тестирования хранилища данных, как описано в разделе Как проверить конфигурацию хранилища данных). Если эта роль слишком широкая, вы можете добавить разрешение storage.buckets.get в существующую роль.

  Если вы хотите изменить существующую роль или создать специальную роль, добавьте в нее следующие разрешения:

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (требуется только для тестирования хранилища данных, как описано в разделе Как проверить конфигурацию хранилища данных)

Как настроить Google BigQuery

Прежде чем экспортировать данные в Google BigQuery:

• Убедитесь, что в вашем проекте Google Cloud Platform включены API BigQuery и Cloud Resource Manager. Инструкции приведены в разделе Как включить 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 Credentials Vault, необходимо определить потребителя учетных данных.

При создании хранилища данных с помощью интерфейса Edge, как описано ниже, Edge автоматически создает потребителя, используемого для доступа к учетным данным.

Как проверить конфигурацию хранилища данных

При создании хранилища данных Edge не проверяет, действительны ли ваши учетные данные и конфигурация хранилища данных. Это означает, что вы можете создать хранилище данных и не обнаружить никаких ошибок, пока не запустите первый экспорт данных.

Вы также можете проверить конфигурацию хранилища данных перед его созданием. Тестирование полезно, поскольку экспорт большого объема данных может занять много времени. Проверив учетные данные и конфигурацию хранилища данных до того, как вы начнете скачивать большие объемы данных, вы сможете быстро устранить любые проблемы с настройками.

Если тест пройдет успешно, создайте хранилище данных. Если тест не пройден, исправьте ошибки и повторите проверку конфигурации. Хранилище данных создается только после успешного завершения тестирования.

Чтобы включить функцию тестирования, выполните следующие действия:

• Убедитесь, что в проекте Google Cloud Platform включен Cloud Resource Manager API. Инструкции приведены в разделе Как включить или отключить API.

Как создать хранилище данных

Чтобы создать хранилище данных в интерфейсе:

1. Войдите на страницу https://apigee.com/edge как администратор организации и выберите свою организацию.

   NOTE Создать хранилище данных может только администратор организации Edge.

2. На панели навигации слева выберите Администратор > Хранилища данных Analytics. Откроется страница Хранилища данных Аналитики.

3. Нажмите кнопку + Добавить хранилище данных. Вам будет предложено выбрать тип хранилища данных:

   

4. Выберите тип целевого источника данных для экспорта:

   • Google Cloud Storage
   • Google BigQuery

   Откроется страница конфигурации:

   

5. Введите название хранилища данных.

6. Выберите учетные данные, которые будут использоваться для доступа к хранилищу данных. Появится раскрывающийся список доступных учетных данных.

   Учетные данные зависят от типа хранилища данных. Подробнее о том, как создать сервисный аккаунт для Cloud Storage или BigQuery…

   • Если вы уже загрузили учетные данные, выберите их в раскрывающемся списке. Убедитесь, что вы выбрали учетные данные, подходящие для типа хранилища данных.

   • Если вы добавляете новые учетные данные в хранилище данных, выберите Добавить. В диалоговом окне введите:

     1. Название учетных данных.
     2. Содержимое учетных данных – это ключ сервисного аккаунта в формате JSON, относящийся к вашему хранилищу данных, как описано в разделе Создание сервисного аккаунта для Cloud Storage или BigQuery.
     3. Нажмите Создать.

7. Укажите свойства, относящиеся к типу хранилища данных:

   • Для Google Cloud Storage:

     Свойство	Описание	Обязательно?
     Идентификатор проекта	Идентификатор проекта Google Cloud Platform. Инструкции по созданию проекта Google Cloud Platform приведены в статье Создание проектов и управление ими в документации по Google Cloud Platform.	Да
     Название сегмента	Название сегмента в Cloud Storage, в который вы хотите экспортировать данные Аналитики. Корзина должна существовать до экспорта данных. Инструкции по созданию сегмента Cloud Storage приведены в статье Как создать сегменты хранилища в документации по Google Cloud Platform.	Да
     Путь	Каталог, в котором будут храниться данные аналитики в сегменте Cloud Storage.	Да

   • Для BigQuery:

     Свойство	Описание	Обязательно?
     Идентификатор проекта	Идентификатор проекта Google Cloud Platform. Инструкции по созданию проекта Google Cloud Platform приведены в статье Создание проектов и управление ими в документации по Google Cloud Platform.	Да
     Название набора данных	Название набора данных BigQuery, в который вы хотите экспортировать данные Аналитики. Создайте набор данных до того, как запрашивать экспорт. Инструкции по созданию набора данных BigQuery приведены в статье Как создавать и использовать наборы данных в документации по Google Cloud Platform.	Да
     Префикс таблицы	Префикс для названий таблиц, созданных для данных аналитики в наборе данных BigQuery.	Да

8. Нажмите Проверить подключение, чтобы убедиться, что учетные данные можно использовать для доступа к хранилищу данных.

   Если тест пройдет успешно, сохраните хранилище данных.

   Если тест не пройден, устраните проблемы и повторите попытку. Наведите указатель мыши на сообщение об ошибке в интерфейсе, чтобы посмотреть дополнительную информацию во всплывающей подсказке.

9. После успешного тестирования подключения сохраните хранилище данных.

Как изменить хранилище данных

Чтобы изменить хранилище данных:

1. Войдите на страницу https://apigee.com/edge как администратор организации и выберите свою организацию.

2. На панели навигации слева выберите Администратор > Хранилища данных Analytics. Откроется страница Хранилища данных Аналитики.

3. Наведите указатель мыши на столбец Изменено в отчете, который нужно изменить. Появятся значки изменения и удаления.

4. Изменить или удалить хранилище данных.

5. Если вы изменили хранилище данных, нажмите Проверить подключение, чтобы убедиться, что учетные данные можно использовать для доступа к хранилищу.

   Если тест пройдет успешно, вы сможете посмотреть пример данных в хранилище.

   Если тест не пройден, устраните проблемы и повторите попытку.

6. После того как проверка подключения будет пройдена, обновите хранилище данных.

Как экспортировать данные Аналитики

Чтобы экспортировать данные аналитики, отправьте запрос POST к API /analytics/exports. В теле запроса передаются следующие параметры:

• Название и описание запроса на экспорт
• Диапазон дат экспортируемых данных (значение может охватывать только один день).
• Формат экспортированных данных
• Название хранилища данных
• Включена ли монетизация для организации.

Ниже приведены примеры запросов на экспорт. Полное описание свойств тела запроса приведено в справочнике по свойствам запроса на экспорт.

Ответ на запрос 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.

Чтобы посмотреть статус запроса на экспорт данных, используйте URL, возвращенный в свойстве self, как описано в разделе Как посмотреть статус запроса на экспорт данных из Аналитики. Когда запрос будет выполнен, значение свойства state в ответе будет установлено на completed. После этого вы сможете получить доступ к данным аналитики в хранилище.

Пример 1. Экспорт данных в Cloud Storage

В следующем запросе экспортируется полный набор необработанных данных за последние 24 часа из тестовой среды test организации myorg. Контент экспортируется в Cloud Storage в формате JSON:

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

Чтобы отслеживать статус задания, используйте URI, указанный в свойстве self, как описано в разделе Как посмотреть статус запроса на экспорт данных.

Пример 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>

Чтобы отслеживать статус задания, используйте URI, указанный в свойстве self, как описано в разделе Как посмотреть статус запроса на экспорт данных.

Пример 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 экспорта

Чтобы предотвратить чрезмерное использование дорогостоящих вызовов API экспорта данных, Edge применяет квоту на вызовы API /analytics/exports:

• Для организаций и сред, в которых не включена монетизация, квота составляет:

  • 70 вызовов в месяц на организацию или среду.

  Например, если в вашей организации две среды, prod и test, вы можете выполнять 70 вызовов API в месяц для каждой из них.

• Для организаций и сред с включенной монетизацией квота составляет:

  • 70 вызовов в месяц для каждой организации и среды для стандартных данных.
  • 70 вызовов в месяц для каждой организации и среды для данных монетизации.

  Например, если вы включите монетизацию в организации prod, то сможете сделать 70 вызовов API для стандартных данных и ещё 70 – для данных о монетизации.

Если вы превысите квоту на вызовы, API вернет HTTP-ответ 429.

Как посмотреть статус всех запросов на экспорт данных аналитики

Чтобы посмотреть статус всех запросов на экспорт данных, отправьте запрос GET на адрес /analytics/exports.

Например, следующий запрос возвращает статус всех запросов на экспорт данных аналитики для среды test в организации myorg:

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",
    ... 
  }
]

Как посмотреть статус запроса на экспорт данных аналитики

Чтобы посмотреть статус определенного запроса на экспорт данных Аналитики, отправьте запрос GET на адрес /analytics/exports/{exportId}, где {exportId} – идентификатор, связанный с запросом на экспорт данных Аналитики.

Например, следующий запрос возвращает статус запроса на экспорт данных Аналитики с идентификатором 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"
  }