Связывание API

Введение

API Linking предоставляет надежный интерфейс для настройки и перенаправления пользователей непосредственно к отчету Looker Studio по URL-адресу. Переходя по URL-адресу Linking API, пользователи получают удобный и быстрый доступ к своим данным и возможность взаимодействовать с ними.

В этом документе описан необходимый формат URL-адресов API для связывания и доступные параметры.

Варианты использования и преимущества

API для создания ссылок позволяет предоставлять клиентам предварительно настроенные отчеты для просмотра и взаимодействия с их данными. Основные преимущества API для создания ссылок следующие:

  • Создание отчетов одним щелчком мыши для ваших клиентов .
    • Настройки данных предоставляются в URL-адресе, поэтому пользователям не нужно настраивать отчет под свои данные.
    • Пользователи могут сохранить отчет одним щелчком мыши и вернуться к нему в любое время.
  • Создавайте отчеты в больших масштабах . API для связывания отчетов сокращает время, необходимое для дублирования или создания новых отчетов.
  • Включите интеграцию продуктов . Стабильный интерфейс позволяет интегрировать Looker Studio в рабочий процесс продукта.

Как это работает

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

Связывание рабочего процесса разработчика API

Разработчик подготавливает шаблоны отчетов, источники данных и форматирует URL-адрес API для связывания. Типичный рабочий процесс для разработчиков выглядит следующим образом:

  1. Решите, использовать ли пустой отчет, стандартный шаблон отчета, предоставляемый Looker Studio, или создать отчет Looker Studio, который будет служить шаблоном. Это включает в себя настройку источников данных шаблона.
  2. Сформируйте URL-адрес API для связывания данных в соответствии с вашим конкретным сценарием использования. При необходимости укажите шаблон отчета и другие параметры, включая имя отчета, имя источника данных и конфигурацию источника данных.
  3. Используйте URL-адрес Linking API, чтобы направить пользователей к отчету.

Улучшение пользовательского опыта при использовании API для создания ссылок

Пользователь переходит по URL-адресу Linking API, который, если он правильно настроен разработчиком, перенаправит его на отчет Looker Studio, позволяющий просматривать данные и взаимодействовать с ними. Типичный пользовательский опыт может выглядеть следующим образом:

  1. В браузере пользователь переходит на сервис, интегрированный с Linking API.
  2. Призыв к действию предлагает пользователю перейти по ссылке, чтобы просмотреть свои данные в Looker Studio.
  3. Пользователь переходит по ссылке и попадает на страницу отчета Looker Studio. Отчет загружается, и пользователь может просматривать свои данные и взаимодействовать с ними.
  4. Пользователь нажимает кнопку «Редактировать и поделиться». Отчет сохраняется в его учетной записи Looker Studio.
  5. Теперь пользователь имеет полный доступ и контроль над своей копией отчета. Он может просматривать, редактировать и делиться ею в любое время.

Требования

Для обеспечения корректной работы URL-адреса Linking API необходимо следующее:

  1. Отчет, который служит шаблоном. Если шаблон не предоставлен, можно использовать пустой отчет или отчет по умолчанию, предоставляемый Looker Studio.
  2. Пользователи URL-адреса Linking API должны иметь как минимум доступ на просмотр к шаблону отчета. В зависимости от типа источников данных, используемых в отчете, и конфигурации, предоставленной через Linking API, пользователям также может потребоваться доступ на просмотр к источникам данных. Подробнее см. в разделе «Разрешения для шаблонов» .
  3. Тип коннектора каждого источника данных должен поддерживать настройку через API связывания. Список поддерживаемых коннекторов см. в справочнике по коннекторам.
  4. Пользователи URL-адреса Linking API должны иметь доступ к данным, указанным в URL-адресе Linking API. Если у пользователя нет доступа к базовым данным, все зависимые компоненты отчета будут отображать ошибку.

Параметры URL

URL-адрес API для создания ссылок должен иметь следующий формат:

https://lookerstudio.google.com/reporting/create?parameters

Предполагается, что URL-адрес будет использоваться в контексте веб-браузера, как правило, пользователем, переходящим по ссылке или перенаправляемым на этот URL-адрес. Он также может использоваться для встраивания отчета .

Пример URL

Ниже приведён пример URL-адреса Linking API. Задано имя отчёта и настроен единственный источник данных BigQuery:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.connector=bigQuery
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

Некоторые параметры URL являются обязательными, а некоторые — необязательными. Ниже приведён список параметров, используемых для определения URL-адреса Linking API:

Параметры управления

Параметры управления определяют состояние отчета при просмотре через URL-адрес Linking API.

Имя параметра Описание
c.reportId
Необязательно. Идентификатор отчета шаблона. Looker Studio откроет и настроит указанный отчет. Подробную информацию о том, как найти идентификатор, см. в разделе «Идентификатор отчета» . Если он не указан, используется пустой отчет или шаблон отчета по умолчанию; подробную информацию см. в разделе «Использование пустого отчета или шаблона отчета по умолчанию» .
c.pageId
Необязательный параметр. Идентификатор начальной страницы для загрузки в отчет. По умолчанию используется первая страница отчета, если не указан.
c.mode
Необязательный параметр. Начальный режим отчета. Один из вариантов: view или edit . По умолчанию используется режим view , если не указано иное.
c.explain
Необязательный параметр. Видимость диалогового окна информации/отладки. Установите значение true , чтобы отобразить кнопку диалогового окна. По умолчанию значение false , если параметр не указан. Дополнительную информацию см. в разделе «Устранение неполадок с конфигурацией» .

Пример

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &c.pageId=g7u8s9
  &c.mode=edit
  &r.reportName=MyNewReport
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

Параметры отчета

Параметры отчета переопределяют его свойства.

Имя параметра Описание
r.reportName
Необязательный параметр. Задает имя отчета. Если не указано, по умолчанию используется имя отчета из шаблона.
r.measurementId

Необязательный параметр. Задает идентификаторы показателей Google Analytics для измерения использования отчетов . Используйте запятую для разделения нескольких идентификаторов.

Если r.measurementId и r.keepMeasurementId не указаны, идентификаторы измерений Google Analytics сообщают о значениях по умолчанию, равных "не задано". Если r.measurementId и r.keepMeasurementId заданы, приоритет отдается r.keepMeasurementId при установке идентификатора.

r.keepMeasurementId

Необязательный параметр. Установите значение true , чтобы использовать шаблон отчета «Идентификаторы измерений Google Analytics» . По умолчанию значение false , если не указано.

Если r.measurementId и r.keepMeasurementId не указаны, идентификаторы измерений Google Analytics сообщают о значениях по умолчанию, равных "не задано". Если r.measurementId и r.keepMeasurementId заданы, приоритет отдается r.keepMeasurementId при установке идентификатора.

Пример

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &r.measurementId=G-XXXXXXXXXX
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

Параметры источника данных

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

alias используется для ссылки на источник данных в существующем отчете. Использование псевдонима обеспечивает обратную совместимость, если источник данных добавляется/удаляется из шаблона отчета.

Подробную информацию о том, как найти alias источника данных, см. в разделе «Псевдоним источника данных» .

Параметры источника данных

Следующие параметры являются общими для всех типов разъемов:

Имя Описание
ds. alias .datasourceName

Необязательный параметр. Задает имя источника данных.

Если ds.datasourceName и ds.keepDatasourceName не указаны, имя источника данных по умолчанию определяется на основе соглашения об именовании, включающего тип коннектора и время создания (например, samples - 12/12/21, 10:53 PM ). Если ds.datasourceName и ds.keepDatasourceName заданы, приоритет отдается ds.datasourceName при определении имени источника данных.

ds. alias .keepDatasourceName

Необязательный параметр. Установите значение true , чтобы использовать имя источника данных шаблона. По умолчанию, если не указано иное, значение будет false .

Если ds.datasourceName и ds.keepDatasourceName не указаны, имя источника данных по умолчанию определяется на основе соглашения об именовании, включающего тип коннектора и время создания (например, samples - 12/12/21, 10:53 PM ). Если ds.datasourceName и ds.keepDatasourceName заданы, приоритет отдается ds.datasourceName при определении имени источника данных.

ds. alias .connector
Необязательный.

Тип соединителя источника данных. Дополнительную информацию о поддерживаемых типах соединителей см. в справочнике по соединителям .

Если этот параметр задан, то все необходимые параметры коннектора для данного типа коннектора должны быть указаны в URL-адресе Linking API, и конфигурация источника данных шаблона будет полностью заменена.

Если параметр не указан, то в URL-адресе API для связывания можно указать ноль или более параметров коннектора для данного типа коннектора. Для указания любых параметров, не указанных в URL-адресе API для связывания, будет использоваться конфигурация источника данных шаблона. Подробную информацию о том, как определить тип коннектора источника данных шаблона, см. в разделе «Тип коннектора» .

Чтобы узнать больше о том, как параметр ds.connector влияет на то, будет ли конфигурация источника данных шаблона заменена полностью или использована для обновления неуказанных параметров, см. раздел «Замена или обновление» .

ds. alias .refreshFields
Необязательный.

Установите значение true , чтобы использовать конфигурацию источника данных, указанную через API связывания, для обновления полей источника данных и обновления компонентов отчета с новыми выбранными полями. true обычно указывается при переключении типа коннектора или для типов коннекторов, где изменение конфигурации приводит к изменению полей (например, поля для источников данных BigQuery часто изменяются при различных конфигурациях таблиц).

Установите значение false , чтобы поля источника данных остались неизменными по сравнению с шаблоном отчета. Значение false обычно указывается, когда новая конфигурация данных дает точно такие же поля, и вы хотите сохранить все изменения полей, внесенные в источник данных шаблона.

Если значение не указано, параметры по умолчанию различаются в зависимости от типа коннектора. Для получения информации о параметрах по умолчанию для конкретных коннекторов, если вы хотите изменить поведение по умолчанию, обратитесь к справочнику по коннекторам .

Рекомендации по использованию refreshFields :
  • Если refreshFields установлен в значение false , а конфигурация источника данных, указанная через Linking API, приводит к получению полей, отличных от тех, которые используются в шаблоне отчета, пользователь, скорее всего, увидит ошибку конфигурации для затронутых компонентов.
  • Изменения полей в шаблоне источника данных (например, имя, тип, агрегация и т. д.) не переносятся в новые источники данных, если refreshFields установлен в true . Установите refreshFields в false , чтобы сохранить конфигурацию полей из шаблона источника данных.
  • Вычисляемые поля и параметры, определенные в источниках данных шаблона, всегда будут копироваться в новые создаваемые источники данных и не зависят от значения параметра refreshFields .
ds. alias .connectorParameters
Обязательно . Конфигурация источника данных для типа соединителя . Подробную информацию о том, как определить соединитель, используемый для создания источника данных, см. в разделе «Тип соединителя» . Подробную информацию о параметрах источника данных, доступных для каждого типа соединителя, см. в справочнике по соединителям .

Замена или обновление — конфигурации источников данных

При настройке параметров источника данных наличие или отсутствие параметра ds.connector в URL-адресе Linking API указывает на намерение заменить или обновить конфигурацию шаблона источника данных соответственно.

В таблице ниже подробно описано, как параметр ds.connector влияет на то, будет ли конфигурация источника данных шаблона заменена полностью или использована для обновления неуказанных параметров:

Установлен ли параметр ds.connector ? Ожидаемая конфигурация и поведение Типичное использование
Да Замените . Конфигурация источника данных шаблона будет заменена полностью с использованием параметров источника данных, указанных в URL-адресе API связывания. Необходимо указать все обязательные параметры для типа коннектора. См. раздел «Обязательные параметры, если задан параметр ds.connector .
  • При изменении типа коннектора источника данных. Например, если вы настроили источник данных BigQuery в шаблоне отчета, но хотите настроить источник данных Sheets через Linking API, потребуется полностью определить новую конфигурацию коннектора.
  • Когда необходимо гарантировать правильность конфигурации источника данных, замена конфигурации позволяет избежать использования неизвестных значений из шаблона источника данных.
Нет Обновление . Конфигурация источника данных шаблона будет использоваться для указания любых параметров, не указанных в URL-адресе API связывания. Все параметры коннектора для типа коннектора являются необязательными, если не указано иное.

Это упрощает URL-адрес API для связывания и обычно рекомендуется, если вы знакомы с конфигурацией источника данных шаблона и хотите переопределить только часть параметров.
  • Когда вам нужно указать только значения параметров, отличающиеся от значений в шаблоне источника данных, и вы готовы использовать шаблон источника данных для любых неуказанных параметров коннектора. Например, измените только идентификатор проекта выставления счетов в конфигурации источника данных BigQuery и используйте конфигурацию шаблона для всех остальных параметров.

Обязательные параметры при установке параметра ds.connector

Если параметр ds.connector источника данных указан, то все параметры коннектора, помеченные как «Обязательные», должны быть указаны для этого источника данных. Если параметр ds.connector источника данных не указан, то все параметры коннектора, даже те, которые помечены как обязательные, могут рассматриваться как необязательные, если не указано иное.

Примеры

Настраивает отчет с использованием одного источника данных BigQuery ( ds0 ) и полностью заменяет конфигурацию источника данных:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare

Если отчет использует один источник данных, псевдоним источника данных можно опустить. Приведенный выше URL-адрес можно упростить до следующего:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.datasourceName=MyNewDataSource
  &ds.connector=bigQuery
  &ds.type=TABLE
  &ds.projectId=bigquery-public-data
  &ds.datasetId=samples
  &ds.tableId=shakespeare

Настраивает отчет с использованием одного источника данных BigQuery ( ds0 ) и обновляет только идентификатор проекта выставления счетов этого источника данных:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.billingProjectId=my-billing-project

Настраивает отчет с двумя источниками данных: источником данных BigQuery ( ds0 ) и источником данных Google Analytics ( ds1 ). Конфигурация источника данных BigQuery заменяется полностью, в то время как конфигурация Google Analytics обновляет один параметр и использует шаблон источника данных ds1 для любых неуказанных параметров коннектора:

https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &r.reportName=MyNewReportWithMultipleDataSources
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare
  &ds.ds1.viewId=92320289

Создать против Добавить

Иногда бывает полезно использовать один и тот же источник данных в нескольких отчетах, чтобы обновления источника данных влияли на все отчеты одновременно. При создании отчета с помощью Linking API вы можете повторно добавить источник данных из шаблона отчета, убедившись, что выполнены все следующие условия:

  1. Источник данных является многоразовым (см. раздел «Встроенные и многоразовые источники данных »).
  2. В URL-адресе отсутствует ссылка на источник данных по псевдониму.
  3. В URL-адресе не используется псевдоним с подстановочным знаком (см. Подстановочный знак для псевдонима источника данных ).

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

псевдоним источника данных подстановочный знак

Для применения параметра Linking API к нескольким источникам данных вместо псевдонима источника данных можно использовать псевдоним ds.* с подстановочным знаком.

Это может быть полезно для удаления повторяющихся параметров из вашего URL-адреса. Например, если у вас есть шаблон с тремя подключенными источниками данных BigQuery, и вы хотите заменить projectId и datasetId в каждом из них, но сохранить tableId , вы можете написать это так:

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.ds1.projectId=client-project
  &ds.ds1.datasetId=client-dataset
  &ds.ds2.projectId=client-project
  &ds.ds2.datasetId=client-dataset
  &ds.ds3.projectId=client-project
  &ds.ds3.datasetId=client-dataset

Или, используя символ подстановки ds.* , вы можете использовать следующий эквивалентный URL-адрес:

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset

Параметры, передаваемые в Linking API и не использующие подстановочный ds.* , имеют приоритет над параметрами, которые его используют. В приведенном выше примере вы можете добавить конкретный псевдоним источника данных, чтобы переопределить значение, полученное с помощью подстановочного знака.

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset
  &ds.ds1.datasetId=client-dataset

В более общем случае порядок приоритета параметров следующий:

  1. Параметр, заданный с помощью определенного псевдонима ( ds.ds1.datasetId ).
  2. Параметр, заданный с использованием подстановочного знака ( ds.*.datasetId ).
  3. Значение, полученное из источника данных шаблона, если параметр ds.connector не указан (см. Замена против обновления ).
  4. Значение по умолчанию для параметра, если он является необязательным.

Справочник по разъемам

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

BigQuery

Коннектор BigQuery поддерживает два типа запросов: запрос TABLE , в котором указывается идентификатор таблицы, к которой нужно обратиться, и запрос CUSTOM_QUERY , в котором указывается SQL-запрос к таблице.

Запросы к таблицам

Следующие параметры применяются, если для type установлено значение TABLE и вы указываете идентификатор таблицы для запроса.

Имя параметра Описание
ds. alias .connector
Необязательно. Для коннектора BigQuery установите значение bigQuery .

Если задано, заменяет источник данных предоставленной конфигурацией BigQuery. См. «Замена против обновления» .
ds. alias .type
Обязательно ** Тип запроса. Установите значение TABLE .
ds. alias .projectId
Обязательно ** Идентификатор проекта таблицы, к которой выполняется запрос.
ds. alias .datasetId
Обязательно ** Идентификатор набора данных таблицы, к которой выполняется запрос.
ds. alias .tableId
Обязательно ** Идентификатор таблицы, по которой выполняется запрос.

Таблицы с сегментацией по датам :
При запросах к таблицам с сегментацией по датам поддерживается использование символа * (подстановочный знак) или суффикса YYYYMMDD .
Если таблица идентифицирована как Google Analytics, Firebase Analytics или Firebase Crashlytics, будет выбран шаблон полей по умолчанию, если он не указан отдельно. См. параметры, относящиеся к таблице шаблонов полей .
ds. alias .billingProjectId
Необязательный параметр. Идентификатор проекта, используемый для выставления счетов. Если не указан, будет использоваться projectId .
ds. alias .isPartitioned
Необязательный параметр. Установите значение true , если таблица секционирована и вы хотите использовать столбец секционирования в качестве измерения диапазона дат. Это применимо только к секционированию по времени (например, с использованием столбца секционирования по времени или псевдостолбца _PARTITIONTIME ) и не работает для таблиц с секционированием по целочисленному диапазону. По умолчанию значение false , если не указано. Для получения дополнительной информации см. раздел «Введение в секционированные таблицы» .
ds. alias .refreshFields
Необязательный параметр. По умолчанию имеет значение true , если не указано иное. Подробнее см. refreshFields .
Шаблон полей для Google Analytics, Firebase Analytics и Crashlytics

Для таблиц, идентифицированных как Google Analytics, Firebase Analytics или Firebase Crashlytics, доступны дополнительные параметры для установки шаблона полей. Если параметр не указан, будет выбран шаблон по умолчанию.

Имя Описание
ds. alias .gaTemplateLevel
Необязательно. Шаблон полей Google Analytics для использования. Применяется только при запросе к экспорту данных из таблицы Google Analytics в BigQuery. Один из вариантов: ALL , SESSION , HITS . Для таблиц Google Analytics по умолчанию используется ALL , если не указано иное.
ds. alias .firebaseTemplateLevel
Необязательный параметр. Шаблон полей Firebase Analytics для использования. Применяется только при запросе к экспорту BigQuery для таблицы Firebase Analytics. Может быть установлен только на EVENTS . Для таблиц Firebase Analytics по умолчанию используется EVENTS , если не указано иное.
ds. alias .crashlyticsTemplateLevel
Шаблон полей Firebase Crashlytics для использования. Может быть установлен только в DEFAULT . Применимо только при запросе к экспорту BigQuery для таблицы Firebase Crashlytics. Для таблиц Firebase Crashlytics по умолчанию используется значение DEFAULT , если оно не указано.

Пользовательские запросы

Следующие параметры применяются, если для type установлено значение CUSTOM_QUERY и вы предоставляете SQL-запрос к таблице.

Имя параметра Описание
ds. alias .connector
Необязательно. Для коннектора BigQuery установите значение bigQuery .

Если задано, заменяет источник данных предоставленной конфигурацией BigQuery. См. «Замена против обновления» .
ds. alias .type
Обязательно ** Тип запроса. Установите значение CUSTOM_QUERY .
ds. alias .sql
Обязательно ** SQL-запрос для выполнения.
ds. alias .billingProjectId
Необязательный параметр. Идентификатор проекта, используемого для выставления счетов. Если не задан, будет использоваться projectId . Если projectId не задан, будет использоваться проект из запрашиваемой таблицы.
ds. alias .sqlReplace

Необязательно. Разделенный запятыми список шаблонов и строк замены, которые будут применены к SQL-запросу. Замена строк применяется только в том случае, если найдено совпадение с шаблоном. Используйте запятую для разделения пар шаблон и строк замены. Например: stringPattern1,replacementString1, stringPattern2,replacementString2 .

ds. alias .refreshFields
Необязательный параметр. По умолчанию имеет значение true , если не указано иное. Подробнее см. refreshFields .

Примеры

Конфигурация типа TABLE , в которой запрос определяется с помощью идентификатора таблицы:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare
  &ds.ds0.billingProjectId=myProject

Конфигурация типа TABLE для запроса к таблице с сегментацией по датам с использованием символа-заменителя:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=price-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=stock_*
  

Конфигурация типа TABLE для запроса к таблице с сегментацией по датам с использованием суффикса YYYYMMDD :

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=price-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=stock_YYYYMMDD
  

Конфигурация типа TABLE для запроса к таблице экспорта BigQuery для Google Analytics с использованием шаблона полей SESSION :

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=my-gabq-project
  &ds.ds0.datasetId=1234567
  &ds.ds0.tableId=ga_sessions_YYYYMMDD
  &ds.ds0.gaTemplateLevel=SESSION
  

Конфигурация типа TABLE для запроса к таблице, секционированной по времени приема данных, с использованием столбца секционирования в качестве измерения диапазона дат:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=acme-co-logs
  &ds.ds0.datasetId=logs
  &ds.ds0.tableId=logs_table
  &ds.ds0.isPartitioned=true

Конфигурация типа CUSTOM_QUERY , в которой запрос определяется с помощью SQL-запроса:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=CUSTOM_QUERY
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.sql=SELECT%20word%2C%20word_count%20FROM%20%60bigquery-public-data.samples.shakespeare%60
  &ds.ds0.billingProjectId=myProject

Конфигурация типа CUSTOM_QUERY , в которой обновляется только SQL-запрос, а для остальной части конфигурации используется источник данных шаблона:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sql=SELECT%20corpus%20FROM%20%60bigquery-public-data.samples.shakespeare%60

Конфигурация типа CUSTOM_QUERY , в которой SQL-запрос источника данных шаблона обновляется с помощью sqlReplace :

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sqlReplace=bigquery-public-data,new-project,samples,new-dataset

# The following shows a template query before and after sqlReplace is applied.
#
# Template data source custom query:
#   SELECT word, word_count FROM big-query-public-data.samples.shakespeare
#   INNER JOIN
#   SELECT word, word_count FROM big-query-public-data.samples.raleigh
#
# New data source custom query with sqlReplace applied:
#   SELECT word, word_count FROM new-project.new-dataset.shakespeare
#   INNER JOIN
#   SELECT word, word_count FROM new-project.new-dataset.raleigh

Облачный гальник

Имя параметра Описание
ds. alias .connector
Необязательно. Для коннектора Cloud Spanner установите значение cloudSpanner .

Если задано, заменяет источник данных предоставленной конфигурацией Cloud Spanner. См. Заменить или обновить .
ds. alias .projectId
Обязательно ** Идентификатор проекта.
ds. alias .instanceId
Обязательно ** Идентификатор экземпляра.
ds. alias .databaseId
Обязательно ** Идентификатор базы данных.
ds. alias .sql
Обязательно ** SQL-запрос для выполнения.
ds. alias .refreshFields
Необязательный параметр. По умолчанию имеет значение true , если не указано иное. Подробнее см. refreshFields .

Пример

Конфигурация Cloud Spanner с SQL-запросом:

https://lookerstudio.google.com/reporting/create?
  c.reportId=456def
  &ds.ds1.connector=cloudSpanner
  &ds.ds1.projectId=myProject
  &ds.ds1.instanceId=production
  &ds.ds1.datasetId=transactions
  &ds.ds1.sql=SELECT%20accountId%2C%20date%2C%20revenue%20FROM%20sales%3B

Связи между членами сообщества

Имя параметра Описание
ds. alias .connector
Необязательно. Установите значение community для подключения к сообществу .

Если задано, заменяет источник данных предоставленной конфигурацией Community Connector. См. Заменить или обновить .
ds. alias .connectorId
Обязательно ** connectorId коннектора сообщества (также известный как идентификатор deploymentId ).
ds. alias .parameters
Необязательно. Дополнительные параметры, специфичные для коннектора, определяются конфигурацией коннектора сообщества.
ds. alias .refreshFields
Необязательный параметр. По умолчанию имеет значение true , если не указано иное. Подробнее см. refreshFields .

Пример

Подключитесь к коннектору сообщества, указав параметры конфигурации state и city :

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=community
  &ds.ds5.connectorId=AqwqXxQshl94nJa0E0-1MsZXQL0DfCsJIMWk7dnx
  &ds.ds5.state=CA
  &ds.ds5.city=Sacramento

Google Аналитика

Имя параметра Описание
ds. alias .connector
Необязательно. Для подключения к Google Analytics установите значение googleAnalytics .

Если задано, заменяет источник данных предоставленной конфигурацией Google Analytics. См. Заменить или обновить .
ds. alias .accountId
Обязательно ** Идентификатор учетной записи.
ds. alias .propertyId
Обязательно ** Идентификатор объекта недвижимости.
ds. alias .viewId
Идентификатор представления.
Обязательно ** для использования с ресурсами Universal Analytics.
Не задавайте эти параметры для свойств Google Analytics 4.
ds. alias .refreshFields
Необязательный параметр. По умолчанию — false , если не указан. Подробнее см. refreshFields .

Примеры

Настройка Google Analytics для ресурса Universal Analytics:

https://lookerstudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=UA-54516992-1
  &ds.ds2.viewId=92320289

Настройка Google Analytics для ресурса Google Analytics 4:

https://lookerstudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=213025502

Google Облачное хранилище

Имя параметра Описание
ds. alias .connector
Необязательно. Установите значение для коннектора Google Cloud Storage googleCloudStorage .

Если задано, заменяет источник данных предоставленной конфигурацией Google Cloud Storage. См. Заменить или обновить .
ds. alias .pathType
Обязательно ** Тип пути. Используйте FILE для выбора одного файла или FOLDER для выбора всех файлов по указанному пути.
ds. alias .path
Обязательно ** Путь к файлу (например, MyBucket/MyData/MyFile.csv ), если pathType имеет значение FILE , или путь к папке (например , *MyBucket/MyData ), если pathType имеет FOLDER .
ds. alias .refreshFields
Необязательный параметр. По умолчанию имеет значение true , если не указано иное. Подробнее см. refreshFields .

Пример

Настройка Google Cloud Storage для одного файла:

https://lookerstudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FILE
  &ds.ds50.path=MyBucket%2FMyData%2FMyFile.csv

Настройки Google Cloud Storage для всех файлов по указанному пути:

https://lookerstudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FOLDER
  &ds.ds50.path=MyBucket%2FMyData

Google Таблицы

Имя параметра Описание
ds. alias .connector
Необязательно. Для подключения к Google Sheets установите значение googleSheets .

Если задано, заменяет источник данных предоставленной конфигурацией Google Sheets. См. Заменить или обновить .
ds. alias .spreadsheetId
Обязательно ** Идентификатор электронной таблицы.
ds. alias .worksheetId
Обязательно ** Идентификатор листа.
ds. alias .hasHeader
Необязательный параметр. Установите значение true , чтобы использовать первую строку в качестве заголовков. По умолчанию значение true , если параметр не указан. Заголовки столбцов должны быть уникальными. Столбцы с пустыми заголовками не будут добавлены в источник данных.
ds. alias .includeHiddenCells
Необязательный параметр. Установите значение true , чтобы включить скрытые ячейки. По умолчанию значение true , если не указано.
ds. alias .includeFilteredCell
Необязательный параметр. Установите значение true , чтобы включить отфильтрованные ячейки. Если параметр не указан, по умолчанию будет установлено значение true .
ds. alias .range
Необязательно. Диапазон, например, A1:B52.
ds. alias .refreshFields
Необязательный параметр. По умолчанию имеет значение true , если не указано иное. Подробнее см. refreshFields .

Примеры

Настройка Google Таблиц:

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437

Конфигурация Google Sheets, в которой первая строка используется в качестве заголовков, а ячейки скрыты и отфильтрованы:

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437
  &ds.ds3.hasHeader=true
  &ds.ds3.includeHiddenCells=true
  &ds.ds3.includeFilteredCells=true

Конфигурация Google Sheets с диапазоном ячеек (A1:D20):

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437
  &ds.ds3.range=A1%3AD20

Лукер

Имя параметра Описание
ds. alias .connector
Необязательно. Установите значение looker для коннектора Looker .

Если задано, заменяет источник данных предоставленной конфигурацией Looker. См. Заменить или обновить .
ds. alias .instanceUrl
Обязательно ** URL-адрес экземпляра Looker.
ds. alias .model
Обязательно ** Модель Looker.
ds. alias .explore
Обязательно ** Looker Explore.
ds. alias .refreshFields
Необязательный параметр. По умолчанию — false , если не указан. Подробнее см. refreshFields .

Пример

Подключитесь к Looker Explore:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=looker
  &ds.ds5.instanceUrl=my.looker.com
  &ds.ds5.model=thelook
  &ds.ds5.explore=orders

Консоль поиска

Имя параметра Описание
ds. alias .connector
Необязательно. Установите значение searchConsole для коннектора Search Console .

Если задано, заменяет источник данных предоставленной конфигурацией Search Console. См. Заменить или обновить .
ds. alias .siteUrl
Обязательно ** URL сайта. Для свойства Domain добавьте префикс sc-domain\: .
ds. alias .tableType
Обязательный параметр. ** Задает тип таблицы. Может быть одним из значений SITE_IMPRESSION или URL_IMPRESSION .
ds. alias .searchType
Обязательно ** Задает тип поиска. Может быть одним из следующих значений: WEB , IMAGE , VIDEO или NEWS .
ds. alias .refreshFields
Необязательный параметр. По умолчанию — false , если не указан. Подробнее см. refreshFields .

Пример

Настройка свойства URL-префикса в Search Console:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=searchConsole
  &ds.ds5.siteUrl=https%3A%2F%2Fwww.example.com%2Fwelcome
  &ds.ds5.tableType=SITE_IMPRESSION
  &ds.ds5.searchType=WEB

Настройка свойства домена в Search Console:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  ds.ds5.connector=searchConsole
  &ds.ds5.siteUrl=sc-domain%3Aexample.com
  &ds.ds5.tableType=SITE_IMPRESSION
  &ds.ds5.searchType=WEB

Разрешения шаблона

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

В таблице ниже представлен рекомендуемый доступ к источникам данных для оптимального взаимодействия с пользователем на основе шаблонов источников данных и конфигурации Linking API:

тип источника данных Настройка API-интерфейса для источника данных. Рекомендации по правам доступа к источникам данных Примечания
Встроенный Заменять Неприменимо — Доступ к просмотру будет унаследован от отчета. Если у пользователя есть доступ на просмотр к шаблону отчета, он автоматически получит доступ на просмотр к любому встроенному источнику данных.
Встроенный Обновлять Неприменимо — Доступ к просмотру будет унаследован от отчета. Если у пользователя есть доступ на просмотр к шаблону отчета, он автоматически получит доступ на просмотр к любому встроенному источнику данных.
Многоразовый Заменять Пользователям не требуется доступ для просмотра. Поскольку конфигурация источника данных полностью заменяется через API связывания, доступ для просмотра не требуется.
Многоразовый Обновлять Пользователям требуется доступ для просмотра. Для того чтобы API связывания мог считывать и использовать конфигурацию из шаблона источника данных, необходим доступ на просмотр источника данных. Если у пользователей нет доступа на просмотр, при загрузке отчета они получат ошибку.

Используйте пустой или стандартный отчет.

Чтобы использовать пустой отчет или отчет по умолчанию, настройте API для связывания следующим образом:

Тип отчета Установите параметр управления reportId Задайте параметры источника данных ( ds ). Примечания
Пустой отчет Нет Нет
Отчет по умолчанию Нет Да

Отчет по умолчанию предоставляется программой Looker Studio.

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

В приведенных ниже примерах показаны различные URL-адреса Linking API, использующие пустой или стандартный отчет.

Начните процесс создания отчета с пустого отчета:

https://lookerstudio.google.com/reporting/create

Запустите процесс создания отчета, создав пустой отчет и задав его имя:

https://lookerstudio.google.com/reporting/create?r.reportName=MyNewReport

Используйте шаблон отчета по умолчанию с конфигурацией коннектора Google Sheets:

https://lookerstudio.google.com/reporting/create?
  ds.connector=googleSheets
  &ds.spreadsheetId=1Q-w7KeeJj1jk3wFcFm4NsPlppNscs0CtHf_EP9fsYOo
  &ds.worksheetId=0

Встроить отчет

Для встраивания отчета, созданного с помощью Linking API, задайте параметры URL и укажите путь /embed/ . URL для встраивания с помощью Linking API должен иметь следующий вид:

https://lookerstudio.google.com/embed/reporting/create?parameters

Найти идентификаторы и псевдонимы

Идентификатор отчета

Чтобы найти идентификатор отчета:

  1. Откройте отчет, который хотите использовать в качестве шаблона. Проверьте URL-адрес отчета. Часть между reporting/ и /page — это идентификатор отчета. Например, в следующем URL-адресе 0B_U5RNpwhcE6SF85TENURnc4UjA — это идентификатор отчета:
https://lookerstudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M
В адресной строке браузера отображается URL-адрес отчета Looker Studio. Идентификатор отчета выделен.
Найдите идентификатор отчета (Report ID) в URL-адресе отчета.

псевдоним источника данных

Отчет может содержать несколько источников данных . На каждый источник данных следует ссылаться по его псевдониму.

Чтобы найти псевдоним источника данных:

  1. Отредактируйте отчет.
  2. На панели инструментов выберите Ресурсы > Управление добавленными источниками данных .
  3. Изучите столбец «Псевдоним» , чтобы найти информацию о псевдонимах для каждого источника данных.

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

Список источников данных на странице управления ресурсами «Источники данных». Выделен столбец «Псевдоним».
Псевдоним источника данных можно найти на странице управления источниками данных .

Тип разъема

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

  1. Отредактируйте отчет.
  2. На панели инструментов выберите Ресурсы > Управление добавленными источниками данных .
  3. Изучите столбец «Тип соединителя» , чтобы определить соединитель, использованный для создания источника данных.
Список источников данных на странице управления ресурсами источников данных. Выделен столбец «Тип коннектора».
Тип соединителя источника данных можно найти на странице управления источниками данных .

Советы и устранение неполадок

Если у вас возникли проблемы, ознакомьтесь с приведенной ниже информацией, чтобы выявить потенциальные проблемы и распространенные ошибки конфигурации.

Диалог отладки

Используйте диалоговое окно отладки, чтобы просмотреть конфигурацию API связывания в том виде, в котором она интерпретируется Looker Studio. Это может помочь в отладке проблем с API.

  • При возникновении ошибки во время анализа URL-адреса Linking API автоматически отобразится диалоговое окно с подробной информацией об ошибке.
  • Если возникает ошибка и диалоговое окно автоматически не отображается, найдите кнопку «Информация» в правом верхнем углу отчета. Нажмите на нее для получения дополнительной отладочной информации.
    Информационная кнопка, позволяющая узнать, как был создан отчет.
  • Если информационная кнопка недоступна, вы можете включить ее, добавив параметр &c.explain=true в конец любого URL-адреса Linking API.

Разрешения

Убедитесь, что для типов источников данных и конфигурации Linking API заданы правильные права доступа к шаблонам. Подробнее см. раздел «Права доступа к шаблонам» .

Обновление или замена

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

При выполнении обновления или замены возможно задать недопустимую конфигурацию с неопределенным поведением. Подробнее см. в разделе «Замена или обновление» .

Обновить поля

Если вы настроили имена полей, типы или агрегации для источника данных шаблона, эти изменения будут перенесены в источник данных, настроенный с помощью Linking API, только если параметр ds.refreshFields установлен в false .

Проверьте параметр источника данных ds.refreshFields в URL-адресе вашего Linking API. Если он отсутствует, убедитесь, что значение по умолчанию для каждого типа коннектора соответствует вашему сценарию использования.

Generally, if you have configured fields in the template data source and are certain that new data source configurations via the Linking API will always yield the exact same fields, then setting refreshFields to false is recommended.

For example, if during the creation of a report template, Looker Studio identifies a particular data source field as type Number and you change it to type Year , this field configuration change is now part of the template data source. Any chart in the report template that uses the corrected field will expect a Year and if the chart is time-based it may not render otherwise. If the Linking API is used to provide a new data source configuration that yields the exact same fields, there are two outcomes based on the value of the refreshFields parameter:

  • If set to true , the field configuration from the template data source will not carry-over, and charts may potentially fail to load if they depend on the same field configuration (ie a field of type Year is expected).

  • If set to false , the field configuration from the template data source will carry-over to the new data source and report charts will receive the same fields with the same configuration and load successfully.

Feedback and support

Use the Issue Tracker to report Linking API issues or to provide feedback. See Support for general resources on getting help and asking questions.

Список изменений

06.06.2023

2023-05-22

21.11.2022

2022-11-14

2022-06-15

  • Out of beta
    • The Integration API has been renamed to Linking API .
    • Linking API is out of beta.
  • Added the pageId control parameter to allow linking to a specific report page.
  • Added the mode control parameter to set the report state to View or Edit mode on load.
  • Data sources configurations can now be replaced entirely or partially updated. This behavior is determined by whether the ds.connector parameter is set. See Replace vs update for details.
  • A default template is now used if a report template is not provide using the c.reportId parameter.
  • Added the ds.refreshFields data source parameter. This allows you to control whether data source fields are refreshed when loading a data source configuration.
  • BigQuery connector
    • projectId is not required when type is set to CUSTOM_QUERY .
    • When billingProjectId is not set then the billing project will fallback to projectId or the project of the queried table.
    • Added support for date partitioned tables. Set the isPartitioned parameter to true to use the partition field as a date range dimension.
    • Added support for querying date partitioned tables using the wildcard character or YYYYMMDD table suffix.
    • Added support for querying Google Analytics, Firebase Analytics, or Crashlytics tables and selecting a fields template.
  • Google Таблицы
    • hasHeader defaults to true , consistent with the web UI default.
    • includeHiddenAndFilteredCell split into includeHiddenCells and
    • includeFilteredCells . Both now default to true , consistent with the web UI default.
  • Search Console connector
    • Renamed the propertyType parameter to searchType .
  • Surveys connector
    • surveyId now accepts a single survey ID or a comma-separated list of survey IDs.

2021-12-16

  • Initial release of the Integration API.
    • Supports linking to an existing report and setting the report name.
    • Multiple data sources can be configured and each data source name can be set.
    • Support for the following connector types: BigQuery, Cloud Spanner, Google Analytics, Google Cloud Storage, Google Sheets, Google Surveys, Search Console.