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

Вы просматриваете документацию Apigee Edge .
Перейдите в документацию Apigee X.info

Настройте права доступа для назначенных сервисных агентов.

Для настройки прав доступа для назначенных сервисных агентов в рамках подготовки к описанным выше изменениям выполните следующие шаги.

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 Облачное хранилище
• 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

Прежде чем экспортировать данные в 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 для проверки разрешений перед каждым экспортом.
• Убедитесь, что API BigQuery включен в вашем проекте 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 использует хранилище учетных данных (Credentials Vault) для безопасного хранения учетных данных, используемых для доступа к вашему репозиторию экспортированных данных. Чтобы служба могла получить доступ к учетным данным в хранилище учетных данных Edge, необходимо определить потребителя учетных данных.

При создании хранилища данных с помощью пользовательского интерфейса 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 Cloud Storage :

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