В этом документе представлен полный справочник по запросам и ответам для API отчетов по многоканальным последовательностям.
Введение
API отчетов по многоканальным последовательностям позволяет запрашивать данные отчетов по многоканальным последовательностям Google Analytics. Каждый отчет состоит из статистики, полученной на основе данных, которые код отслеживания отправляет обратно в Analytics, и организованных в виде параметров и показателей. Выбирая собственные комбинации параметров и показателей, вы можете использовать API отчетов для создания индивидуальных отчетов с учетом ваших требований.
API содержит единственный метод, который запрашивает данные отчета: report.get. С помощью этого метода вы предоставляете идентификатор таблицы, соответствующий представлению (профилю), для которого вы хотите получить данные. Кроме того, вы указываете следующее:
- Комбинация параметров и показателей.
- Диапазон дат.
- Набор параметров опции, которые управляют тем, какие данные возвращаются.
API делает метод report.get доступным в конечной точке REST: https://www.googleapis.com/analytics/v3/data/mcf . В следующем разделе показан пример запроса и описан каждый из параметров.
Запрос
API предоставляет единственный метод запроса данных:
analytics.data.mcf.get()
API также можно запросить как конечную точку REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Каждый параметр запроса URL-адреса указывает параметр запроса API, который должен быть закодирован в URL-адресе .
Все запросы к API отчетности по многоканальным последовательностям должны быть авторизованы, желательно через OAuth 2.0 .
Сводка параметров запроса
В следующей таблице приведены все параметры запроса, принимаемые API отчетов по многоканальным последовательностям. Щелкните имя каждого параметра, чтобы просмотреть подробное описание.
| Имя | Ценить | Необходимый | Краткое содержание |
|---|---|---|---|
ids | string | да | Уникальный идентификатор таблицы в формате ga:XXXX, где XXXX — это идентификатор представления (профиля) Analytics, для которого запрос будет получать данные. |
start-date | string | да | Дата начала получения данных Google Analytics. Запросы могут указывать дату начала в формате YYYY-MM-DD или относительную дату (например, today , yesterday или NdaysAgo , где N — положительное целое число). |
end-date | string | да | Дата окончания получения данных Google Analytics. В запросе может быть указана дата окончания в формате YYYY-MM-DD или относительная дата (например, today , yesterday или NdaysAgo , где N — положительное целое число). |
metrics | string | да | Список показателей, разделенных запятыми, например mcf:totalConversions,mcf:totalConversionValue . В допустимом запросе должна быть указана хотя бы одна метрика. |
dimensions | string | нет | Список разделенных запятыми параметров отчета «Многоканальные последовательности», например mcf:source,mcf:keyword . |
sort | string | нет | Список разделенных запятыми параметров и показателей, указывающий порядок и направление сортировки возвращаемых данных. |
filters | string | нет | Фильтры параметров или показателей, которые ограничивают данные, возвращаемые по вашему запросу. |
samplingLevel | string | нет | Желаемый уровень выборки. Допустимые значения:
|
start-index | integer | нет | Первая строка извлекаемых данных, начиная с 1. Используйте этот параметр в качестве механизма нумерации страниц вместе с параметром max-results . |
max-results | integer | нет | Максимальное количество строк, включаемых в ответ. |
Подробности параметров запроса
идентификаторы
ids= ga:12345ga: с идентификатором представления (профиля) отчета. Вы можете получить идентификатор представления (профиля) для своего отчета с помощью метода analytics.management.profiles.list , который предоставляет id в ресурсе представления (профиля) в API управления Google Analytics .Дата начала
start-date= 2011-10-01start-date и end-date , сервер вернет ошибку. Значения даты могут относиться к определенной дате, используя шаблон YYYY-MM-DD , или относительными, используя шаблон today , yesterday или NdaysAgo . Значения должны соответствовать [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) .start-date — 2011-01-01 . Верхний предел start-date не ограничен.Пример диапазона дат за последние 7 дней (начиная со вчерашнего дня) с использованием относительных дат:
&start-date=7daysAgo &end-date=yesterday
Дата окончания
end-date= 2011-10-31start-date и end-date , сервер вернет ошибку. Значения даты могут относиться к определенной дате, используя шаблон YYYY-MM-DD , или относительными, используя шаблон today , yesterday или NdaysAgo . Значения должны соответствовать [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) .end-date — 2005-01-01 Для end-date не существует ограничения по верхнему пределу.Пример диапазона дат за последние 10 дней (начиная с сегодняшнего дня) с использованием относительных дат:
&start-date=9daysAgo &end-date=today
размеры
dimensions= mcf:source,mcf:keyword Параметр Dimensions определяет основные ключи данных для отчета «Многоканальные последовательности», например mcf:source или mcf:medium . Используйте параметры, чтобы сегментировать показатели конверсии. Например, хотя вы можете запросить общее количество конверсий на ваш сайт, возможно, было бы интереснее запросить количество конверсий, сегментированных по каналам. В этом случае вы увидите количество конверсий из органических, реферальных, электронных писем и т. д.
При использовании dimensions в запросе данных помните о следующих ограничениях:
- В любом запросе можно указать максимум 7 параметров.
- Вы не можете отправить запрос, состоящий только из параметров: вы должны объединить любые запрошенные параметры хотя бы с одной метрикой.
Недоступные значения
Если значение измерения невозможно определить, Analytics использует специальную строку (не задана).
метрики
metrics= mcf:totalConversions,mcf:totalConversionValue Совокупная статистика активности пользователей на вашем сайте, например общее количество конверсий или общая ценность конверсий. Если в запросе нет параметра dimensions , возвращаемые метрики предоставляют совокупные значения для запрошенного диапазона дат, например общую общую ценность конверсий. Однако при запросе измерений значения сегментируются по значению измерения. Например, mcf:totalConversions запрошенный с помощью mcf:source возвращает общее количество конверсий для каждого источника.
При запросе показателей имейте в виду:
- Любой запрос должен предоставить хотя бы одну метрику; запрос не может состоять только из измерений.
- Для любого запроса можно указать максимум 10 показателей.
Сортировать
sort= mcf:source,mcf:mediumСписок метрик и измерений, указывающий порядок и направление сортировки возвращаемых данных.
- Порядок сортировки определяется порядком перечисленных показателей и параметров слева направо.
- Направление сортировки по умолчанию — по возрастанию, но его можно изменить на нисходящее, используя префикс знака минус (
-) в запрошенном поле.
Сортировка результатов запроса позволяет задавать различные вопросы о ваших данных. Например, чтобы ответить на вопрос «Каковы мои основные источники конверсий и через какие каналы?» вы можете сделать запрос со следующим параметром. Сначала он сортируется по mcf:source , а затем по mcf:medium , оба в порядке возрастания:
sort=mcf:source,mcf:medium
Чтобы ответить на соответствующий вопрос «Какие у меня самые популярные средства конверсии и из каких источников?», вы можете выполнить запрос со следующим параметром. Сначала он сортируется по mcf:medium , а затем по mcf:source , оба в порядке возрастания:
sort=mcf:medium,mcf:source
При использовании параметра sort имейте в виду следующее:
- Сортируйте только по значениям параметров или показателей, которые вы использовали в параметрах
dimensionsилиmetrics. Если ваш запрос сортируется по полю, которое не указано ни в параметрах, ни в параметрах показателей, вы получите сообщение об ошибке. - По умолчанию строки сортируются в возрастающем алфавитном порядке в локали en-US .
- По умолчанию числа сортируются в порядке возрастания.
- По умолчанию даты сортируются по возрастанию.
фильтры
filters= mcf:medium %3D%3Dreferral Параметр строки запроса filters ограничивает данные, возвращаемые по вашему запросу. Чтобы использовать параметр filters , укажите параметр или показатель для фильтрации, а затем выражение фильтра. Например, следующий запрос запрашивает mcf:totalConversions и mcf:source для представления (профиля) 12134 , где измерение mcf:medium — это referral на строку:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Подробности читайте в справочнике по Core Reporting API .
уровень выборки
samplingLevel=DEFAULT-
DEFAULT— возвращает ответ с размером выборки, обеспечивающим баланс скорости и точности. -
FASTER— возвращает быстрый ответ с меньшим размером выборки. -
HIGHER_PRECISION— возвращает более точный ответ с использованием большого размера выборки, но это может привести к замедлению ответа.
DEFAULT .максимальные результаты
max-results=100 Максимальное количество строк, которые можно включить в этот ответ. Вы можете использовать это в сочетании с start-index для получения подмножества элементов или использовать его отдельно, чтобы ограничить количество возвращаемых элементов, начиная с первого. Если max-results не указан, запрос возвращает максимум по умолчанию — 1000 строк.
API отчетности по многоканальным последовательностям возвращает максимум 10 000 строк на запрос, независимо от того, сколько вы запрашиваете. Он также может вернуть меньше строк, чем запрошено, если сегментов измерения не так много, как вы ожидаете. Например, существует менее 300 возможных значений для mcf:medium , поэтому при сегментации только по среде вы не сможете получить более 300 строк, даже если вы установите max-results более высокое значение.
Ответ
В случае успеха этот запрос возвращает тело ответа со структурой JSON, определенной ниже.
Примечание . Термин «результаты» относится ко всему набору строк, соответствующих запросу, а термин «ответ» относится к набору строк, возвращаемых на текущей странице результатов. Они могут отличаться, если общее количество результатов превышает размер страницы текущего ответа, как описано в itemsPerPage .
Формат ответа
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
Поля ответа
Свойства структуры тела ответа определяются следующим образом:
| Имя свойства | Ценить | Описание |
|---|---|---|
kind | string | Тип ресурса. Значение: «analytics#mcfData». |
id | string | Идентификатор для этого ответа данных. |
query | object | Этот объект содержит все значения, передаваемые в качестве параметров запроса. Значение каждого поля объясняется в описании соответствующего ему параметра запроса . |
query.start-date | string | Дата начала. |
query.end-date | string | Дата окончания. |
query.ids | string | Уникальный идентификатор таблицы. |
query.dimensions[] | list | Список измерений аналитики. |
query.metrics[] | list | Список метрик аналитики. |
query.sort[] | list | Список метрик или измерений, по которым сортируются данные. |
query.filters | string | Список фильтров метрик или параметров, разделенных запятыми. |
query.samplingLevel | string | Requested sampling level. |
query.start-index | integer | Начальный индекс строк. Значение по умолчанию — 1. |
query.max-results | integer | Максимум результатов на странице. |
startIndex | integer | Начальный индекс строк, заданный параметром запроса start-index . Значение по умолчанию — 1. |
itemsPerPage | integer | Максимальное количество строк, которое может содержать ответ, независимо от фактического количества возвращаемых строк. Если указан параметр запроса max-results , значение itemsPerPage будет меньшим из max-results или 10 000. Значение по умолчанию для itemsPerPage — 1000. |
totalResults | integer | Общее количество строк в результате запроса независимо от количества строк, возвращенных в ответе. Для запросов, результатом которых является большое количество строк, totalResults может быть больше, чем itemsPerPage . См. раздел «Пейджинг» для получения дополнительных объяснений totalResults и itemsPerPage для больших запросов. |
selfLink | string | Ссылка на эту страницу результатов для этого запроса данных. |
previousLink | string | Ссылка на предыдущую страницу результатов для этого запроса данных. |
nextLink | string | Ссылка на следующую страницу результатов для этого запроса данных. |
profileInfo | object | Информация о представлении (профиле), для которого были запрошены данные. Данные просмотра (профиля) доступны через API управления Google Analytics. |
profileInfo.profileId | string | Идентификатор представления (профиля), например 1174 . |
profileInfo.accountId | string | Идентификатор учетной записи, которой принадлежит это представление (профиль), например 30481 . |
profileInfo.webPropertyId | string | Идентификатор веб-ресурса, которому принадлежит это представление (профиль), например UA-30481-1 . |
profileInfo.internalWebPropertyId | string | Внутренний идентификатор веб-ресурса, которому принадлежит это представление (профиль), например UA-30481-1 . |
profileInfo.profileName | string | Имя представления (профиля). |
profileInfo.tableId | string | Идентификатор таблицы для представления (профиля), состоящий из «ga:», за которым следует идентификатор представления (профиля). |
containsSampledData | boolean | Истинно, если ответ содержит выборочные данные. |
sampleSize | string | Количество выборок, используемых для расчета выборочных данных. |
sampleSpace | string | Общий размер пространства выборки. Это указывает на общий доступный размер выборочного пространства, из которого были выбраны выборки . |
columnHeaders[] | list | Заголовки столбцов, в которых перечислены имена измерений, за которыми следуют имена метрик. Порядок параметров и показателей такой же, как указан в запросе через параметры metrics и dimensions . Количество заголовков – это количество измерений + количество метрик. |
columnHeaders[].name | string | Название параметра или показателя. |
columnHeaders[].columnType | string | Тип столбца. Либо «РАЗМЕР», либо «МЕТРИЧЕСКИЙ». |
columnHeaders[].dataType | string | Тип данных. Заголовки столбцов измерения имеют в качестве типа данных только "STRING" или "MCF_SEQUENCE" . Заголовки столбцов показателей имеют типы данных для значений показателей, такие как "INTEGER" , "DOUBLE" , "CURRENCY" и т. д. |
totalsForAllResults | object | Общие значения запрошенных метрик в виде пар ключ-значение имен и значений метрик. Порядок итогов показателей такой же, как порядок показателей, указанный в запросе. |
rows[] | list | Строки данных отчета, где каждая строка содержит список объектов Объект
{
"primitiveValue": "2183"
}
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Коды ошибок
API отчетов по многоканальным последовательностям возвращает код состояния HTTP 200 , если запрос успешен. Если при обработке запроса возникает ошибка, API возвращает код и описание ошибки. Каждое приложение, использующее аналитический API, должно реализовать правильную логику обработки ошибок. Подробную информацию о кодах ошибок и способах их обработки можно найти в справочном руководстве «Реакция на ошибку» .
Попробуй это!
Используйте API-обозреватель ниже, чтобы вызвать этот метод для реальных данных и просмотреть ответ.
Выборка
Google Analytics рассчитывает определенные комбинации параметров и показателей на лету. Чтобы вернуть данные в разумные сроки, Google Analytics может обрабатывать только выборку данных.
Вы можете указать уровень выборки, который будет использоваться для запроса, задав параметр sampleLevel .
Если ответ MCF Reporting API содержит выборочные данные, то поле ответа containsSampledData будет иметь true . Кроме того, два свойства предоставят информацию об уровне выборки для запроса: sampleSize и sampleSpace . С помощью этих двух значений вы можете рассчитать процент сеансов, использованных для запроса. Например, если sampleSize — 201,000 , а sampleSpace — 220,000 , то отчет основан на (201 000 / 220 000) * 100 = 91,36% сеансов.
См. раздел «Выборка» для получения общего описания выборки и того, как она используется в Google Analytics.
Обработка результатов больших данных
Если вы ожидаете, что ваш запрос вернет большой набор результатов, используйте приведенные ниже рекомендации, которые помогут вам оптимизировать запрос API, избежать ошибок и минимизировать превышение квоты . Обратите внимание, что мы установили базовый уровень производительности, разрешив использование максимум 7 параметров и 10 показателей в одном запросе API. Хотя обработка некоторых запросов, в которых указано большое количество метрик и параметров, может занять больше времени, чем другие, ограничения количества запрашиваемых метрик может быть недостаточно для повышения производительности запросов. Вместо этого вы можете использовать следующие методы для достижения наилучших результатов производительности.
Уменьшение размеров каждого запроса
API позволяет указать до 7 измерений в одном запросе. Google Analytics часто приходится вычислять результаты этих сложных запросов на лету. Это может занять особенно много времени, если количество результирующих строк велико. Например, запрос ключевых слов по городам и часам может соответствовать миллионам строк данных. Вы можете повысить производительность, уменьшив количество строк, которые Google Analytics должен обрабатывать, ограничив количество измерений в вашем запросе.
Разделение запроса по диапазону дат
Вместо пролистывания результатов по дате для одного длинного диапазона дат рассмотрите возможность формирования отдельных запросов для одной недели или даже одного дня. Конечно, для большого набора данных даже запрос данных за один день может вернуть больше, чем max-results , и в этом случае нельзя избежать разбиения по страницам. Но в любом случае, если количество совпадающих строк для вашего запроса превышает max-results , разделение диапазона дат может сократить общее время получения результатов. Этот подход может повысить производительность как в однопоточных, так и в параллельных запросах.
Пейджинг
Пролистывание результатов может оказаться полезным способом разбить большие наборы результатов на управляемые фрагменты. Поле totalResults сообщает, сколько существует совпадающих строк, а itemsPerPage указывает максимальное количество строк, которые могут быть возвращены в результате. Если соотношение totalResults и itemsPerPage высокое, отдельные запросы могут выполняться дольше, чем необходимо. Если вам нужно только ограниченное количество строк, например, для целей отображения, вам может оказаться удобным установить явное ограничение на размер ответа с помощью параметра max-results . Однако если вашему приложению необходимо полностью обработать большой набор результатов, запрос максимально допустимого количества строк может быть более эффективным.
Использование gzip
Простой и удобный способ уменьшить пропускную способность, необходимую для каждого запроса, — включить сжатие gzip. Хотя для распаковки результатов требуется дополнительное время процессора, компромисс с сетевыми затратами обычно делает это очень выгодным. Чтобы получить ответ в кодировке gzip, вы должны сделать две вещи: установить заголовок Accept-Encoding и изменить свой пользовательский агент, чтобы он содержал строку gzip . Вот пример правильно сформированных HTTP-заголовков для включения сжатия gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)