Вы просматриваете документацию Apigee Edge .
Перейдите в документацию Apigee X.info
Edge API Analytics собирает и анализирует широкий спектр статистической информации из каждого запроса и ответа API. Эта информация собирается автоматически и может быть отображена в пользовательском интерфейсе Edge или с помощью API метрик. Дополнительную информацию об этих статистических данных см. в разделах «Метрики» и «Измерения» .
Вы также можете захотеть собрать пользовательские аналитические данные, специфичные для ваших API-прокси, приложений, продуктов или разработчиков. Например, вы можете собирать данные из параметров запроса, заголовков запроса, тел запросов и ответов, а также переменных, которые вы определяете в своих API.
В этой теме показано, как использовать политику StatisticsCollector для извлечения пользовательских аналитических данных из запроса/ответа API и передачи этих данных в Edge API Analytics. Затем показано, как просмотреть аналитические данные в отчете в пользовательском интерфейсе Edge или с помощью Edge API.
О Google Book API
В этой теме описывается, как получать пользовательские аналитические данные из запросов API-прокси к Google Books API . Google Books API позволяет искать книги по названию, теме, автору и другим характеристикам.
Например, отправьте запросы к конечной точке /volumes для выполнения поиска по названию книги. Передайте в API книг один параметр запроса, содержащий название книги:
curl https://www.googleapis.com/books/v1/volumes?q=davinci%20code
В результате выполнения запроса возвращается JSON-массив найденных элементов, соответствующих критериям поиска. Ниже показан первый элемент массива в ответе (обратите внимание, что для простоты часть содержимого опущена):
{ "kind": "books#volumes", "totalItems": 1799, "items": [ { "kind": "books#volume", "id": "ohZ1wcYifLsC", "etag": "4rzIsMdBMYM", "selfLink": "https://www.googleapis.com/books/v1/volumes/ohZ1wcYifLsC", "volumeInfo": { "title": "The Da Vinci Code", "subtitle": "Featuring Robert Langdon", "authors": [ "Dan Brown" ], "publisher": "Anchor", "publishedDate": "2003-03-18", "description": "MORE THAN 80 MILLION COPIES SOLD ....", "industryIdentifiers": [ { "type": "ISBN_10", "identifier": "0385504217" }, { "type": "ISBN_13", "identifier": "9780385504218" } ], "readingModes": { "text": true, "image": true }, "pageCount": 400, "printType": "BOOK", "categories": [ "Fiction" ], "averageRating": 4.0, "ratingsCount": 710, "maturityRating": "NOT_MATURE", "allowAnonLogging": true, "contentVersion": "0.18.13.0.preview.3", "panelizationSummary": { "containsEpubBubbles": false, "containsImageBubbles": false }, ... "accessInfo": { "country": "US", "viewability": "PARTIAL", "embeddable": true, "publicDomain": false, "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY", "epub": { "isAvailable": true, "acsTokenLink": "link" }, "pdf": { "isAvailable": true, "acsTokenLink": "link" }, ... } }
Обратите внимание, что несколько областей ответа выделены:
- Количество результатов поиска
- Средняя оценка книги
- Количество оценок
- Доступны PDF-версии книги.
В следующих разделах описывается, как собирать статистические данные по этим областям ответа, а также по параметру запроса q , содержащему критерии поиска.
Создайте API-прокси для Google Book API.
Прежде чем собирать статистику для Google Book API, необходимо создать прокси-сервер Edge API, который будет вызывать этот API. Затем вы используете этот прокси-сервер для отправки запросов к Google Book API.
Шаг 2: Создание API-прокси. В руководстве по созданию API-прокси описано, как создать прокси, который вызывает API https://mocktarget.apigee.net . Обратите внимание, что для вызова прокси, описанного в этом руководстве, не требуется ключ API.
Используйте ту же процедуру для создания API-прокси для конечной точки /volumes API Google Books. На шаге 5 процедуры при создании API-прокси установите следующие свойства, чтобы они ссылались на API Google Books:
- Имя прокси : "mybooksearch"
- Базовый путь прокси : "/mybooksearch"
- Существующий API : "https://www.googleapis.com/books/v1/volumes"
После создания и развертывания прокси-сервера вы сможете вызывать его с помощью команды curl следующего вида:
curl http://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code
где org_name и env_name указывают организацию и среду, в которой вы развернули прокси. Например:
curl http://myorg-test.apigee.net/mybooksearch?q=davinci%20code
Собирайте пользовательские аналитические данные.
Сбор аналитических данных из API-запроса — это двухэтапная процедура:
Извлеките интересующие вас данные и запишите их в переменную.
Все данные, передаваемые в Edge API Analytics, поступают из значений, хранящихся в переменных. Некоторые данные автоматически сохраняются в предопределенных переменных потока Edge, например, значения параметров запроса, передаваемых в API-прокси. Дополнительную информацию о предопределенных переменных потока см. в разделе «Обзор переменных потока ».
Используйте политику «Извлечение переменных» , чтобы извлечь пользовательское содержимое из запроса или ответа и записать эти данные в переменную.
Запись данных из переменной в Edge API Analytics.
Используйте политику «Сборщик статистики» для записи данных из переменной в Edge API Analytics. Данные могут поступать из предопределенных переменных потока Edge или переменных, созданных политикой «Извлечение переменных».
После сбора статистических данных вы можете использовать пользовательский интерфейс управления Edge или API для получения и фильтрации статистики. Например, вы можете создать пользовательский отчет, показывающий средний рейтинг для каждого названия книги, где название книги соответствует значению параметра запроса, переданного в API.
Используйте политику «Извлечение переменных» для извлечения аналитических данных.
Аналитические данные необходимо извлечь и сохранить в переменную — либо в переменную потока, предопределенную Edge, либо в пользовательские переменные, которые вы определяете, — прежде чем их можно будет передать в API Analytics. Для записи данных в переменную используется политика «Извлечение переменных» .
Политика «Извлечение переменных» позволяет анализировать полезную нагрузку сообщений с помощью выражений JSONPath или XPath. Для извлечения информации из результатов поиска JSON в Google Book API используйте выражение JSONPath. Например, чтобы извлечь значение averageRating из первого элемента массива результатов JSON, выражение JSONPath будет следующим:
$.items[0].volumeInfo.averageRating
После обработки JSONPath политика извлечения переменных записывает извлеченное значение в переменную.
В этом примере вы используете политику «Извлечение переменных» для создания четырех переменных:
-
responsejson.totalitems -
responsejson.ratingscount -
responsejson.avgrating -
responsejson.pdf
Для этих переменных responsejson — это префикс переменной, а totalitems , ratingscount , avgrating и pdf — это названия переменных.
Приведенная ниже политика извлечения переменных показывает, как извлекать данные из JSON-ответа и записывать их в пользовательские переменные. Каждый элемент <Variable> использует атрибут name , который указывает имя пользовательской переменной и связанное с ней выражение JSONPath. Элемент <VariablePrefix> указывает префикс переменной.
Добавьте эту политику в свой API-прокси в пользовательском интерфейсе Edge. Если вы создаете API-прокси в формате XML, добавьте политику в файл ExtractVars.xml расположенный в каталоге /apiproxy/policies .
<ExtractVariables name="ExtractVars"> <Source>response</Source> <JSONPayload> <Variable name="totalitems"> <JSONPath>$.totalItems</JSONPath> </Variable> <Variable name="ratingscount"> <JSONPath>$.items[0].volumeInfo.ratingsCount</JSONPath> </Variable> <Variable name="avgrating"> <JSONPath>$.items[0].volumeInfo.averageRating</JSONPath> </Variable> <Variable name="pdf"> <JSONPath>$.items[0].accessInfo.pdf.isAvailable</JSONPath> </Variable> </JSONPayload> <VariablePrefix>responsejson</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Используйте политику «Сборщик статистики» для записи данных в службу аналитики.
Используйте политику сбора статистики для записи данных из переменной в Edge API Analytics. Политика сбора статистики имеет следующий вид:
<StatisticsCollector> <DisplayName>Statistics Collector-1</DisplayName> <Statistics> <Statistic name="statName" ref="varName" type="dataType">defVal</Statistic> … </Statistics> </StatisticsCollector>
где:
- statName указывает имя, которое вы используете для ссылки на статистические данные в пользовательском отчете.
- varName указывает имя переменной, содержащей собираемые аналитические данные. Эта переменная может быть встроена в Edge или создана пользователем с помощью политики извлечения переменных.
dataType указывает тип данных, которые записываются: строка, целое число, число с плавающей запятой, длинное целое число, число с плавающей запятой или логическое значение.
Для данных строкового типа вы ссылаетесь на статистические данные как на измерение в пользовательском отчете. Для числовых типов данных (целое число/число с плавающей запятой/длинное число/число с плавающей запятой) вы ссылаетесь на статистические данные либо как на измерение , либо как на метрику в пользовательском отчете.
- defValue может дополнительно предоставлять значение по умолчанию для пользовательской переменной, которое отправляется в API Analytics, если переменные не могут быть разрешены или переменная не определена.
В приведенном ниже примере вы используете политику «Сборщик статистики» для сбора данных для переменных, созданных политикой «Извлечение переменных». Вы также собираете значение параметра запроса, передаваемого каждому вызову API. Для ссылки на параметры запроса используйте предопределенную переменную потока :
request.queryparam.queryParamName
Для параметра запроса с именем "q" используйте следующую ссылку:
request.queryparam.q
Добавьте эту политику в свой API-прокси через пользовательский интерфейс Edge или, если вы создаете API-прокси в формате XML, добавьте файл AnalyzeBookResults.xml, в папку /apiproxy/policies со следующим содержимым:
<StatisticsCollector name="AnalyzeBookResults"> <Statistics> <Statistic name="totalitems" ref="responsejson.totalitems" type="integer">0</Statistic> <Statistic name="ratingscount" ref="responsejson.ratingscount" type="integer">0</Statistic> <Statistic name="avgrating" ref="responsejson.avgrating" type="float">0.0</Statistic> <Statistic name="pdf" ref="responsejson.pdf" type="boolean">true</Statistic> <Statistic name="booktitle" ref="request.queryparam.q" type="string">none</Statistic> </Statistics> </StatisticsCollector>
Прикрепите политики к потоку ответов ProxyEntpoint.
Для корректной работы необходимо прикрепить политики к потоку прокси API в соответствующем месте. В данном случае политики должны выполняться после получения ответа от Google Book API и до отправки ответа запрашивающему клиенту. Поэтому прикрепите политики к предварительному потоку ответа ProxyEndpoint .
В приведенном ниже примере конфигурации ProxyEndpoint сначала выполняется политика ExtractVars для анализа ответного сообщения. Затем политика AnalyzeBookResults пересылает эти значения в API Analytics:
<ProxyEndpoint name="default">
><PreFlow name="PreFlow">
<Request/>
<Response>
<Step>
<Name>Extract-Vars</Name>
</Step>
<Step>
<Name>AnalyzeBookResults</Name>
</Step>
</Response>
</PreFlow>
<HTTPProxyConnection>
<!-- Base path used to route inbound requests to this API proxy -->
<BasePath>/mybooksearch</BasePath>
<!-- The named virtual host that defines the base URL for requests to this proxy -->
<VirtualHost>default</VirtualHost>
</HTTPProxyConnection>
<RouteRule name="default">
<!-- Connects the proxy to the target defined under /targets -->
<TargetEndpoint>default</TargetEndpoint>
</RouteRule>
</ProxyEndpoint>Разверните API-прокси
После внесения этих изменений необходимо развернуть настроенный вами API-прокси.
Заполнить аналитические данные
После развертывания API-прокси вызовите его для заполнения данных в API Analytics. Это можно сделать, выполнив следующие команды, каждая из которых использует название книги:
Моби Дик:
curl https://org_name-env_name.apigee.net/mybooksearch?q=mobey%20dick
Код да Винчи:
curl https://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code
Исчезнувшая:
curl https://org_name-env_name.apigee.net/mybooksearch?q=gone%20girl
Игра престолов:
curl https://org_name-env_name.apigee.net/mybooksearch?q=game%20of%20thrones
Просмотреть аналитические данные
Edge предоставляет два способа просмотра ваших пользовательских аналитических данных:
- Пользовательский интерфейс Edge поддерживает создание пользовательских отчетов, позволяющих отображать данные в виде графических диаграмм.
- API метрик позволяет получать аналитические данные, выполняя REST-запросы к Edge API. Вы можете использовать API для создания собственных визуализаций в виде пользовательских виджетов, которые можно встраивать в порталы или пользовательские приложения.
Создайте отчет со статистикой, используя пользовательский интерфейс Edge.
Пользовательские отчеты позволяют детально изучить статистику конкретного API и просмотреть именно те данные, которые вам нужны. Вы можете создать пользовательский отчет, используя любые метрики и измерения , встроенные в Edge. Кроме того, вы можете использовать любые аналитические данные, извлеченные с помощью политики StatisticsCollector .
При создании политики сбора статистики вы указываете тип собираемых данных. Для строкового типа данных используйте статистические данные в качестве измерения в пользовательском отчете. Для числовых типов данных (целое число/число с плавающей запятой/длинное число/число с плавающей запятой двойной точности) используйте статистические данные в пользовательском отчете в качестве измерения или показателя. Дополнительные сведения см. в разделе «Управление пользовательскими отчетами» .
Создание пользовательского отчета с помощью интерфейса Edge:
- Перейдите на страницу «Пользовательские отчеты», как описано ниже.
Край
Чтобы получить доступ к странице «Пользовательские отчеты» с помощью интерфейса Edge:
- Войдите на сайт apigee.com/edge .
- В левой панели навигации выберите «Анализ» > «Пользовательские отчеты» > «Отчеты» .
Классический Edge (частное облако)
Чтобы получить доступ к странице «Пользовательские отчеты» с помощью классического интерфейса Edge:
- Войдите в систему по
http:// ms-ip :9000, где ms-ip — это IP-адрес или DNS-имя узла сервера управления. В верхней панели навигации выберите Analtyics > Отчеты .
- На странице «Пользовательские отчеты» нажмите кнопку «+Пользовательский отчет» .
- Укажите название отчета , например, mybookreport .
Выберите встроенный показатель , например, «Трафик» , и агрегатную функцию , например, «Сумма» .
Или выберите один из числовых статистических показателей, созданных с помощью политики StatisticsCollector. Например, выберите ratingscount и агрегатную функцию Sum .
Выберите встроенное измерение , например, API Proxy , или любую из строковых или числовых статистических данных, созданных с помощью политики StatisticsCollector.
Например, выберите название книги . В отчете теперь будет отображаться сумма оценок по названию книги :
- Выберите «Сохранить» . Отчет появится в списке всех пользовательских отчетов.
Для запуска отчета выберите его название. По умолчанию отчет отображает данные за последний час.
- Чтобы задать временной диапазон, выберите поле отображения даты в правом верхнем углу, чтобы открыть всплывающее окно выбора даты .
Выберите «Последние 7 дней» . Отчет обновится, отображая сумму оценок по каждому названию книги:
Получайте статистику с помощью Edge API.
Используйте API метрик Edge для получения статистики по вашим пользовательским аналитическим данным. В приведенном ниже примере запроса:
- Ресурс, указанный в URL-адресе после
/statsопределяет желаемое измерение . В этом примере вы получаете данные для измеренияbooktitle. - Параметр запроса
selectуказывает, какие метрики необходимо получить. Этот запрос возвращает аналитические данные на основе суммыratingscount. Параметр
timeRangeзадает временной интервал для возвращаемых данных. Временной диапазон имеет следующий формат:MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
Полный вызов API выглядит следующим образом:
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00" / -u email:password
Вы должны увидеть ответ в следующем формате:
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(ratingscount)",
"values": [
"5352.0"
]
}
],
"name": "gone girl"
},
{
"metrics": [
{
"name": "sum(ratingscount)",
"values": [
"4260.0"
]
}
],
"name": "davinci code"
},
{
"metrics": [
{
"name": "sum(ratingscount)",
"values": [
"1836.0"
]
}
],
"name": "game of thrones"
},
{
"metrics": [
{
"name": "sum(ratingscount)",
"values": [
"1812.0"
]
}
],
"name": "mobey dick"
}
],
"name": "prod"
}
],
"metaData": {
"errors": [],
"notices": [
"query served by:9b372dd0-ed30-4502-8753-73a6b09cc028",
"Table used: uap-prod-gcp-us-west1.edge.edge_api_raxgroup021_fact",
"Source:Big Query"
]
}
}API метрик Edge предлагает множество опций. Например, вы можете сортировать результаты в порядке возрастания или убывания. В следующем примере используется порядок возрастания:
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&sort=ASC" / -u email:password
Результаты также можно отфильтровать, указав значения интересующих параметров. В приведенном ниже примере отчет отфильтрован по результатам для фильмов «Исчезнувшая» и «Код да Винчи»:
$ curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&filter=(booktitle%20in%20'gone%20girl'%2C%20'davinci%20code')" / -u email:password
Создание пользовательских аналитических переменных с помощью конструктора решений.
Конструктор решений позволяет создавать пользовательские аналитические переменные с помощью простого в использовании диалогового окна управления.
Возможно, вам будет полезно прочитать предыдущий раздел «Сбор пользовательских аналитических данных» , в котором объясняется, как политики «Извлечение переменных» и «Сборщик статистики» работают вместе, передавая пользовательские переменные в Edge API Analytics. Как вы увидите, пользовательский интерфейс следует той же схеме, но предоставляет удобный способ настройки всего через интерфейс. При желании попробуйте пример с Google Books API, используя пользовательский интерфейс вместо редактирования и прикрепления политик вручную.
Диалоговое окно «Конструктор решений» позволяет настраивать аналитические переменные непосредственно в пользовательском интерфейсе. Этот инструмент генерирует политики и прикрепляет их к API-прокси. Политики извлекают интересующие переменные из запросов или ответов и передают извлеченные переменные в Edge API Analytics.
Конструктор решений создает новые политики извлечения переменных и сбора статистики и присваивает им уникальные имена. Конструктор решений не позволяет вернуться назад и изменить эти политики после их создания в рамках определенной версии прокси-сервера. Для внесения изменений редактируйте сгенерированные политики непосредственно в редакторе политик.
- Перейдите на страницу «Обзор» вашего прокси-сервера в пользовательском интерфейсе Edge.
- Нажмите «Разработка» .
- На странице «Разработка» выберите в меню «Инструменты» пользовательскую коллекцию аналитических данных . Откроется диалоговое окно «Конструктор решений».
- В диалоговом окне «Конструктор решений» сначала настраиваются две политики: «Извлечение переменных» и «Сборщик статистики». Затем указывается, куда следует прикрепить эти политики.
- Укажите данные, которые вы хотите извлечь:
- Тип местоположения: Выберите тип данных, которые вы хотите собрать, и место их сбора. Вы можете выбрать данные со стороны запроса или ответа. Например, Запрос: Параметр запроса или Ответ: Тело XML.
- Источник местоположения: Укажите данные, которые вы хотите собрать. Например, имя параметра запроса или XPath для XML-данных в теле ответа.
- Укажите имя (и тип) переменной, которую политика сбора статистики будет использовать для идентификации извлеченных данных. См. ограничения на именование в этом разделе.
Используемое вами имя отобразится в выпадающем меню «Измерения» или «Метрики» в пользовательском интерфейсе конструктора пользовательских отчетов. - Выберите место в потоке API-прокси, куда вы хотите прикрепить сгенерированные политики извлечения переменных и статистики. Для получения рекомендаций см. раздел « Прикрепление политик к потоку ответов ProxyEndpoint ». Для корректной работы политики должны быть прикреплены к потоку API-прокси в соответствующем месте. Необходимо прикрепить политики на том этапе потока, где перехватываемые переменные находятся в области видимости (заполнены).
- Нажмите +Collector , чтобы добавить дополнительные пользовательские переменные.
После завершения нажмите кнопку «Создать решение» .
- Сохраните и разверните прокси-сервер.
Теперь вы можете создать пользовательский отчет на основе этих данных, как описано выше.