Анализ содержимого сообщений API с помощью пользовательской аналитики

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

Edge API Analytics собирает и анализирует широкий спектр статистической информации по каждому запросу и ответу API. Эта информация собирается автоматически и затем может отображаться в пользовательском интерфейсе Edge или с помощью API метрик. Дополнительные сведения об этой статистике см. в разделе «Метрики и измерения» .

Вы также можете собрать пользовательские аналитические данные, относящиеся к вашим прокси-серверам API, приложениям, продуктам или разработчикам. Например, вы можете захотеть собрать данные из параметров запроса, заголовков запросов, тел запросов и ответов или переменных, которые вы определяете в своих API.

В этом разделе показано, как использовать политику СтатистикаКоллектор для извлечения пользовательских аналитических данных из запроса/ответа API и передачи этих данных в Edge API Analytics. Затем показано, как просмотреть аналитические данные в отчете в пользовательском интерфейсе Edge или с помощью Edge API.

Об API Google Книги

В этом разделе описывается, как собирать пользовательские аналитические данные из запросов прокси-сервера API к API Google Книг . API Google Книг позволяет искать книги по названию, теме, автору и другим характеристикам.

Например, отправьте запросы к конечной точке /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 для API Google Книги.

Прежде чем вы сможете собирать статистику для Google Book API, вы должны создать прокси-сервер Edge API, который будет его вызывать. Затем вы вызываете этот прокси-сервер API, чтобы отправлять запросы к API Google Книги.

Шаг 2. Создайте прокси-сервер API. В руководстве по созданию прокси-сервера API описано, как создать прокси-сервер, который вызывает API https://mocktarget.apigee.net . Обратите внимание, что прокси-сервер, описанный в этом руководстве, не требует ключа API для его вызова.

Используйте ту же процедуру, чтобы создать прокси-сервер API для конечной точки /volumes API Google Книги. На шаге 5 процедуры при создании прокси-сервера API установите следующие свойства для ссылки на API Google Книг:

  • Имя прокси : «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 представляет собой двухэтапную процедуру:

  1. Извлеките интересующие данные и запишите их в переменную.

    Все данные, передаваемые в Edge API Analytics, поступают из значений, хранящихся в переменных. Некоторые данные автоматически сохраняются в предопределенных переменных потока Edge, например значения параметров запроса, передаваемых прокси-серверу API. Дополнительную информацию о предопределенных переменных потока см. в разделе Обзор переменных потока .

    Используйте политику извлечения переменных , чтобы извлечь пользовательское содержимое из запроса или ответа и записать эти данные в переменную.

  2. Запишите данные из переменной в Edge API Analytics.

    Используйте политику сборщика статистики для записи данных из переменной в Edge API Analytics. Данные могут поступать из предопределенных переменных потока Edge или переменных, созданных политикой извлечения переменных.

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

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

Данные аналитики должны быть извлечены и сохранены в переменной (либо переменной потока, предварительно определенной Edge, либо пользовательскими переменными, которые вы определяете), прежде чем их можно будет передать в API Analytics. Чтобы записать данные в переменную, вы используете политику Extract Variables .

Политика «Извлечение переменных» может анализировать полезные данные сообщений с помощью выражений JSONPath или XPath. Чтобы извлечь информацию из результатов поиска JSON API Google Book, используйте выражение 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, добавьте политику в файл /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 или может быть пользовательской переменной, созданной политикой извлечения переменных.

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

    Для данных строкового типа вы ссылаетесь на статистические данные как на измерение в пользовательском отчете. Для числовых типов данных (целое/с плавающей запятой/длинное/двойное) вы ссылаетесь на статистические данные либо как параметр , либо как показатель в пользовательском отчете.

  • defValue дополнительно предоставляет значение по умолчанию для пользовательской переменной, которое отправляется в API Analytics, если переменные не могут быть разрешены или переменная не определена.

В приведенном ниже примере вы используете политику «Сборщик статистики» для сбора данных для переменных, созданных политикой «Извлечение переменных». Вы также собираете значение параметра запроса, передаваемого при каждом вызове 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 в соответствующем месте. В этом случае политики должны выполняться после получения ответа от API Google Книги и до того, как ответ будет отправлен запрашивающему клиенту. Поэтому прикрепите политики к ответу ProxyEndpoint PreFlow .

В приведенном ниже примере конфигурации 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. Кроме того, вы можете использовать любые аналитические данные, которые вы извлекли с помощью политики СтатистикаКоллектор .

При создании политики сборщика статистики вы указываете тип собираемых данных. Для строкового типа данных используйте ссылку на статистические данные как измерение в пользовательском отчете. Для числовых типов данных (целое/с плавающей запятой/длинное/двойное число) используйте статистическую дату в пользовательском отчете как измерение или показатель. Дополнительные сведения см. в разделе «Управление пользовательскими отчетами» .

Создание пользовательского отчета с помощью пользовательского интерфейса Edge:

  1. Откройте страницу «Пользовательские отчеты», как описано ниже.

    Край

    Чтобы получить доступ к странице «Пользовательские отчеты» с помощью пользовательского интерфейса Edge:

    1. Войдите на сайт apigee.com/edge .
    2. Выберите Анализ > Пользовательские отчеты > Отчеты на левой панели навигации.

    Классический Edge (частное облако)

    Чтобы получить доступ к странице «Пользовательские отчеты» с помощью классического пользовательского интерфейса Edge:

    1. Войдите в систему по http:// ms-ip :9000 , где ms-ip — это IP-адрес или DNS-имя узла сервера управления.

    2. Выберите Аналитика > Отчеты на верхней панели навигации.

  2. На странице «Пользовательские отчеты» нажмите +Пользовательский отчет .
  3. Укажите имя отчета , например mybookreport .

  4. Выберите встроенную метрику , например « Трафик» , и агрегатную функцию , например « Sum» .

    Или выберите одну из статистических данных числовых данных, созданных с помощью политики СтатистикаКоллектор. Например, выберите рейтинги и агрегатную функцию Sum .

  5. Выберите встроенное измерение , например API Proxy , или любую строковую или числовую статистику, созданную вами с помощью политикиStatisticolector.

    Например, выберите название книги . В вашем отчете теперь будет отображаться сумма рейтингов по названиям книг :

    индивидуальный отчет о книге
  6. Выберите Сохранить . Отчет появится в списке всех пользовательских отчетов.

  7. Чтобы запустить отчет, выберите имя отчета. По умолчанию в отчете отображаются данные за последний час.

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

  9. Выберите Последние 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

Создание пользовательских переменных аналитики с помощью Solution Builder

Solution Builder позволяет создавать пользовательские переменные аналитики с помощью простого в использовании диалогового окна пользовательского интерфейса управления.

Возможно, вы захотите прочитать предыдущий раздел «Сбор пользовательских аналитических данных» , в котором объясняется, как политики «Извлечение переменных» и «Сборщик статистики» работают рука об руку для передачи пользовательских переменных в Edge API Analytics. Как вы увидите, пользовательский интерфейс следует тому же шаблону, но предоставляет вам удобный способ настройки всего через пользовательский интерфейс. Если хотите, попробуйте пример API Google Книг, используя пользовательский интерфейс вместо редактирования и прикрепления политик вручную.

Диалоговое окно Solution Builder позволяет настраивать переменные аналитики непосредственно в пользовательском интерфейсе. Этот инструмент генерирует политики и присоединяет их к прокси-серверу API. Политики извлекают интересующие переменные из запросов или ответов и передают извлеченные переменные в Edge API Analytics.

Solution Builder создает новые политики извлечения переменных и сбора статистики и присваивает им уникальные имена. Solution Builder не позволяет вам вернуться назад и изменить эти политики после их создания в данной версии прокси. Чтобы внести изменения, отредактируйте сгенерированные политики непосредственно в редакторе политик.

  1. Перейдите на страницу обзора вашего прокси в пользовательском интерфейсе Edge.
  2. Нажмите «Разработать» .
  3. На странице «Разработка» выберите «Коллекция пользовательской аналитики» в меню «Инструменты». Появится диалоговое окно «Строитель решений».
  4. В диалоговом окне Solution Builder вы сначала настраиваете две политики: «Извлечение переменных» и «Сборщик статистики». Затем вы настраиваете, куда прикрепить эти политики.
  5. Укажите данные, которые вы хотите извлечь:
    • Тип местоположения: выберите тип данных, которые вы хотите собрать, и место их сбора. Вы можете выбрать данные со стороны запроса или ответа. Например, Запрос: Параметр запроса или Ответ: Тело XML.
    • Источник местоположения: укажите данные, которые вы хотите собрать. Например, имя параметра запроса или XPath для XML-данных в тексте ответа.
  6. Укажите имя (и тип) переменной, которую политика сборщика статистики будет использовать для идентификации извлеченных данных. См. ограничения на именование в этом разделе.

    Используемое вами имя появится в раскрывающемся меню параметров или показателей в пользовательском интерфейсе конструктора пользовательских отчетов.
  7. Выберите, где в потоке прокси-сервера API вы хотите прикрепить сгенерированные политики «Извлечение переменных» и «Сборщик статистики». Инструкции см. в разделе « Прикрепление политик к потоку ответов ProxyEndpoint ». Чтобы все работало правильно, политики должны быть прикреплены к потоку прокси-сервера API в соответствующем месте. Вам необходимо прикрепить политики на этапе потока, где перехватываемые вами переменные находятся в области действия (заполнены).
  8. Нажмите +Коллектор , чтобы добавить дополнительные пользовательские переменные.

  9. Когда вы закончите, нажмите « Построить решение» .

  10. Сохраните и разверните прокси.

Теперь вы можете создать собственный отчет для данных, как описано выше.