Экспорт данных из Аналитики

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

Данные Apigee Analytics

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

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

• Значения, разделенные запятыми (CSV)

  Разделителем по умолчанию является запятая (,). Поддерживаемые символы-разделители включают запятую (,), вертикальную черту (|) и табуляцию (\t). Настройте значение с помощью свойства csvDelimiter , как описано в разделе Справочник по свойствам запроса на экспорт .

• JSON (с разделителем новой строки)

  Позволяет использовать символ новой строки в качестве разделителя.

Экспортированные данные включают в себя все аналитические метрики и измерения, встроенные в Edge, а также любые пользовательские аналитические данные, которые вы добавляете. Описание экспортируемых данных см. в разделе «Справочник по метрикам, параметрам и фильтрам Analytics» .

Вы можете экспортировать аналитические данные в следующие хранилища данных:

• Облачное хранилище Google
• Google BigQuery

Обзор процесса экспорта

Следующие шаги суммируют процесс экспорта аналитических данных:

1. Настройте хранилище данных (Cloud Storage или BigQuery) для экспорта данных. Вы должны убедиться, что ваш репозиторий данных настроен правильно и что учетная запись службы, используемая для записи данных в репозиторий данных, имеет правильные разрешения.

2. Создайте хранилище данных , определяющее свойства хранилища данных (Cloud Storage или BigQuery), куда вы экспортируете свои данные, включая учетные данные, используемые для доступа к хранилищу данных.

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

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

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

• Убедитесь, что API BigQuery и Cloud Resource Manager включены в вашем проекте Google Cloud Platform. Инструкции см. в разделе «Включение API» . Apigee использует API BigQuery для использования функций экспорта BigQuery при экспорте в Cloud Storage и API Cloud Resource Manager для проверки разрешения перед каждым экспортом.

• Убедитесь, что учетной записи службы назначены следующие роли:

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

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

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

Настройте Google BigQuery

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

• Убедитесь, что API BigQuery и Cloud Resource Manager включены в вашем проекте Google Cloud Platform. Инструкции см. в разделе «Включение API» . Apigee использует API Cloud Resource Manager для проверки разрешения перед каждым экспортом.
• Убедитесь, что BigQuery API включен в вашем проекте Google Cloud Platform. Инструкции см. в разделе «Включение и отключение 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 не проверяет и не проверяет правильность ваших учетных данных и конфигурации хранилища данных. Это означает, что вы можете создать хранилище данных и не обнаруживать никаких ошибок, пока не запустите первый экспорт данных.

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

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

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

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

Создать хранилище данных

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

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

   ПРИМЕЧАНИЕ . Чтобы создать хранилище данных, вы должны быть администратором организации Edge.

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

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

   

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

   • Облачное хранилище Google
   • Google BigQuery

   Появится страница конфигурации:

   

5. Введите Имя хранилища данных.

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

   Учетные данные зависят от типа хранилища данных. Дополнительные сведения см. в разделе Создание сервисного аккаунта для Cloud Storage или BigQuery .

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

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

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

7. Введите свойства, специфичные для типа хранилища данных:

   • Для облачного хранилища Google :

     Свойство	Описание	Необходимый?
     Идентификатор проекта	Идентификатор проекта Google Cloud Platform. Чтобы создать проект Google Cloud Platform, см. раздел Создание проектов и управление ими в документации Google Cloud Platform.	Да
     Имя сегмента	Имя сегмента в 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. Выберите «Администрирование» > «Хранилища данных аналитики» на левой панели навигации. Откроется страница «Хранилища данных аналитики» .

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. Экспорт данных в облачное хранилище

Следующий запрос экспортирует полный набор необработанных данных за последние 24 часа из тестовой среды в организации 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 для данных монетизации.

Если вы превысите квоту вызовов, 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"
  }