Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация
Edge API Analytics собирает и анализирует разнообразную статистическую информацию из каждого запроса к API и ответа. Эта информация собирается автоматически и может быть показана в интерфейсе Edge или с помощью API показателей. Подробнее о показателях и параметрах…
Вам также может понадобиться собирать специальные данные аналитики, относящиеся к прокси API, приложениям, продуктам или разработчикам. Например, вы можете собирать данные из параметров запроса, заголовков запроса, текста запроса и ответа или переменных, которые вы определяете в своих API.
В этой статье рассказывается, как использовать правило StatisticsCollector, чтобы извлекать из запроса к API/ответа специальные данные аналитики и передавать их в Edge API Analytics. Затем рассказывается, как посмотреть данные аналитики в отчете в интерфейсе Edge или с помощью Edge API.
О Google Book API
В этой статье рассказывается, как собирать пользовательские данные аналитики из запросов прокси-сервера API к Google Книги API. Google Книги API позволяет искать книги по названию, теме, автору и другим характеристикам.
Например, отправьте запрос к конечной точке /volumes, чтобы выполнить поиск по названию книги.
Передайте в Books 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. Затем вы вызываете этот прокси-сервер API, чтобы отправлять запросы к Google Book API.
Шаг 2. Создайте прокси-сервер API. В руководстве по созданию прокси-сервера API рассказывается, как создать прокси-сервер, который вызывает API https://mocktarget.apigee.net. Обратите внимание, что для вызова прокси-сервера, описанного в этом руководстве, не требуется ключ API.
Повторите описанные выше действия, чтобы создать прокси-сервер API для конечной точки /volumes Google Book API. На шаге 5 при создании прокси-сервера API задайте следующие свойства, чтобы ссылаться на Google Книги API:
- Название прокси-сервера: "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, берутся из значений, хранящихся в переменных. Некоторые данные автоматически сохраняются в предопределенных переменных потока Edge, например значения параметров запроса, переданных прокси-серверу API. Подробнее о переменных потока…
Используйте правило Извлечь переменные, чтобы извлечь пользовательский контент из запроса или ответа и записать эти данные в переменную.
Запись данных из переменной в Edge API Analytics.
Используйте правило сбора статистики, чтобы записывать данные из переменной в Edge API Analytics. Данные могут поступать из предопределенных переменных потока Edge или переменных, созданных с помощью правила извлечения переменных.
Собрав статистические данные, вы можете получить и отфильтровать их с помощью интерфейса управления Edge или API. Например, вы можете создать специальный отчет, в котором будет показана средняя оценка для каждого названия книги. Название книги соответствует значению параметра запроса, переданного в API.
Как использовать правило "Извлечь переменные" для извлечения данных аналитики
Чтобы передать данные Аналитики в API Аналитики, их нужно извлечь и сохранить в переменную, например в переменную потока, заданную Edge, или в пользовательскую переменную. Чтобы записать данные в переменную, используйте правило извлечения переменных.
Правило Extract Variables может анализировать полезную нагрузку сообщений с помощью выражений JSONPath или XPath.
Чтобы извлечь информацию из результатов поиска в формате JSON, полученных с помощью Google Books API, используйте выражение JSONPath.
Например, чтобы извлечь значение averageRating из первого элемента массива результатов JSON, нужно использовать следующее выражение JSONPath:
$.items[0].volumeInfo.averageRating
После того как JSONPath будет обработан, правило "Извлечь переменные" запишет извлеченное значение в переменную.
В этом примере вы используете правило извлечения переменных, чтобы создать четыре переменные:
responsejson.totalitemsresponsejson.ratingscountresponsejson.avgratingresponsejson.pdf
В этих переменных responsejson – это префикс, а totalitems, ratingscount, avgrating и pdf – названия.
В приведенном ниже примере правил Extract Variables показано, как извлечь данные из ответа JSON и записать их в пользовательские переменные. Каждый элемент <Variable> использует атрибут name, который задает название настраиваемых переменных и связанное с ними выражение JSONPath.
Элемент <VariablePrefix> указывает префикс переменной.
Добавьте это правило в прокси-сервер API в интерфейсе Edge. Если вы создаете прокси-сервер API в XML, добавьте правило в файл в каталоге /apiproxy/policies с названием ExtractVars.xml:
<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 или пользовательской, созданной с помощью правила Extract Variables.
dataType – тип данных записанных значений: string, integer, float, long, double или boolean.
Для строковых данных статистические данные указываются в параметре специального отчета. Для числовых типов данных (целое число, число с плавающей запятой, длинное целое число, число двойной точности) статистические данные можно использовать в качестве параметра или показателя в специальном отчете.
- defValue при необходимости укажите значение по умолчанию для специальной переменной, которое будет отправляться в API Аналитики, если переменные не могут быть разрешены или переменная не определена.
В приведенном ниже примере используется правило "Сборщик статистики" для сбора данных для переменных, созданных правилом "Извлечение переменных". Вы также собираете значение параметра запроса, переданного каждому вызову API. Чтобы ссылаться на параметры запроса, используйте предопределенную переменную потока:
request.queryparam.queryParamName
Для параметра запроса с названием "q" ссылка будет выглядеть так:
request.queryparam.q
Добавьте это правило в прокси-сервер API в интерфейсе Edge или, если вы создаете прокси-сервер API в XML, добавьте файл в папку /apiproxy/policies с названием AnalyzeBookResults.xml, и следующим содержимым:
<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>
Как прикрепить правила к потоку ответов ProxyEndpoint
Чтобы все работало правильно, правила должны быть прикреплены к потоку прокси-сервера API в нужном месте. В этом случае правила должны выполняться после получения ответа от Google Books API и до отправки ответа клиенту, который отправил запрос. Поэтому прикрепите правила к PreFlow ответа ProxyEndpoint.
В примере конфигурации ProxyEndpoint ниже сначала выполняется правило ExtractVars
для анализа сообщения ответа. Правило AnalyzeBookResults пересылает эти значения в API Аналитики:
<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
Чтобы открыть страницу специальных отчетов в интерфейсе Edge, выполните следующие действия:
- Войдите в аккаунт на сайте apigee.com/edge.
- На панели навигации слева выберите Анализ > Специальные отчеты > Отчеты.
Классическая версия Edge (частное облако)
Чтобы открыть страницу "Специальные отчеты" в классическом интерфейсе Edge:
- Войдите в
http://ms-ip:9000, где ms-ip – это IP-адрес или DNS-имя узла сервера управления. На панели навигации вверху выберите Аналитика > Отчеты.
- На странице "Специальные отчеты" нажмите +Специальный отчет.
- Укажите название отчета, например mybookreport.
Выберите встроенный показатель, например Трафик, и агрегатную функцию, например Сумма.
Или выберите одну из статистических данных, созданных с помощью правила StatisticsCollector. Например, выберите ratingscount и Агрегатную функцию Сумма.
Выберите встроенный параметр, например Прокси API, или любую строковую или числовую статистику, созданную с помощью правила StatisticsCollector.
Например, выберите booktitle. В отчете будет показана сумма значений ratingscount по booktitle:
- Нажмите Сохранить. Отчет появится в списке всех специальных отчетов.
Чтобы запустить отчет, выберите его название. По умолчанию в отчете показываются данные за последний час.
- Чтобы задать диапазон времени, нажмите на дату в правом верхнем углу и откройте всплывающее окно Выбор даты.
Выберите Последние 7 дней. Отчет обновляется и показывает сумму оценок для каждого названия книги:
Как получить статистику с помощью Edge API
Используйте Edge Metrics API, чтобы получать статистику по своим данным аналитики. В примере запроса ниже:
- Ресурс, указанный в 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"
]
}
}Edge metrics 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&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, используйте интерфейс вместо того, чтобы редактировать и прикреплять правила вручную.
В диалоговом окне Solution Builder можно настраивать переменные аналитики прямо в интерфейсе. Этот инструмент создает правила и прикрепляет их к прокси-серверу API. Правила извлекают из запросов или ответов интересующие переменные и передают их в API Аналитики Edge.
Конструктор решений создает новые правила извлечения переменных и сбора статистики и присваивает им уникальные имена. В конструкторе решений нельзя вернуться назад и изменить правила, созданные в определенной версии прокси. Чтобы внести изменения, отредактируйте сгенерированные правила непосредственно в редакторе правил.
- Перейдите на страницу обзора прокси в интерфейсе Edge.
- Нажмите Разработка.
- На странице "Разработка" выберите Сбор данных аналитики в меню "Инструменты". Откроется диалоговое окно Solution Builder (Конструктор решений).
- В диалоговом окне Solution Builder (Конструктор решений) сначала настройте два правила: Extract Variables (Извлечь переменные) и Statistics Collector (Сборщик статистики). Затем вы настраиваете, к чему будут применяться эти правила.
- Укажите, какие данные нужно извлечь:
- Тип местоположения. Выберите тип данных, которые вы хотите собирать, и источник, из которого вы хотите их получать. Вы можете выбрать данные из запроса или ответа. Например, запрос: параметр запроса или ответ: тело XML.
- Источник данных о местоположении. Укажите, какие данные вы хотите собирать. Например, название параметра запроса или XPath для XML-данных в теле ответа.
- Укажите название (и тип) переменной, которую правило "Сборщик статистики" будет использовать для идентификации извлеченных данных. Ознакомьтесь с ограничениями на названия в этой статье.
Выбранное вами название будет отображаться в раскрывающемся меню Параметры или Показатели в интерфейсе создания специальных отчетов. - Выберите, в каком месте потока прокси-сервера API вы хотите прикрепить сгенерированные правила ExtractVariables и Statistics Collector. Инструкции приведены в разделе Как прикрепить правила к потоку ответов ProxyEndpoint. Чтобы все работало правильно, правила должны быть прикреплены к потоку прокси-сервера API в нужном месте. Правила необходимо прикрепить на этапе процесса, когда переменные, которые вы отслеживаете, находятся в области действия (заполнены).
- Чтобы добавить пользовательские переменные, нажмите + Сборщик.
Когда все будет готово, нажмите Создать решение.
- Сохраните и разверните прокси.
Теперь вы можете создать специальный отчет с этими данными, как описано выше.