Связывание API

Введение

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

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

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

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

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

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

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

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

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

  1. Решите, использовать ли пустой отчет, шаблон отчета по умолчанию, предоставленный Looker Studio, или создать отчет Looker Studio, который будет служить шаблоном. Сюда входит настройка источников данных шаблона.
  2. Отформатируйте URL-адрес Linking 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. Тип соединителя каждого источника данных должен поддерживать настройку через Linking API. Список поддерживаемых разъемов см. в справочнике по разъемам .
  4. Пользователи URL-адреса Linking API должны иметь доступ к данным, настроенным в URL-адресе Linking API. Если у пользователя нет доступа к базовым данным, любые зависимые компоненты отчета отобразят ошибку.

параметры URL-адреса

URL-адрес Linking API должен иметь следующую форму:

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

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

Пример URL-адреса

Ниже приведен пример URL-адреса 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. alias .datasourceName

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

Если ds.datasourceName и ds.keepDatasourceName не указаны, имя источника данных по умолчанию соответствует соглашению об именовании, которое включает тип соединителя и время создания (например, образцы — 12.12.21, 22:53 ). Если установлены ds.datasourceName и ds.keepDatasourceName , ds.datasourceName имеет приоритет при установке имени источника данных.

ds. alias .keepDatasourceName ds. alias .keepDatasourceName

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

Если ds.datasourceName и ds.keepDatasourceName не указаны, имя источника данных по умолчанию соответствует соглашению об именовании, которое включает тип соединителя и время создания (например, образцы — 12.12.21, 22:53 ). Если установлены ds.datasourceName и ds.keepDatasourceName , ds.datasourceName имеет приоритет при установке имени источника данных.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Это упрощает URL-адрес Linking 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, он использует учетные данные пользователя, щелкнувшего URL-адрес. Это означает, что у пользователя должен быть доступ к базовым данным, иначе соединение не будет работать. Повторно добавив источник данных в вновь созданный отчет, вы можете сохранить его учетные данные, чтобы пользователи могли продолжать получать доступ к данным в своих новых отчетах.

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

Чтобы применить параметр 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. Значение по умолчанию для параметра, если оно не является обязательным.

Ссылка на разъем

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

Большой запрос

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

ТАБЛИЧНЫЕ запросы

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

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

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

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

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

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

ПОЛЬЗОВАТЕЛЬСКИЕ запросы

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

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

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

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

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

Примеры

Конфигурация типа 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 Export for 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 ds. alias .connector
Необязательный. Установите значение cloudSpanner для соединителя Cloud Spanner .

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

Пример

Конфигурация 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 ds. alias .connector
Необязательный. Установите значение community для соединителя сообщества .

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

Пример

Подключитесь к соединителю сообщества с параметрами конфигурации 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

Гугл Аналитика

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

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

Примеры

Конфигурация 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 ds. alias .connector
Необязательный. Установите соединитель googleCloudStorage Google Cloud Storage .

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

Пример

Конфигурация 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 ds. alias .connector
Необязательный. Установите значение googleSheets для коннектора Google Sheets .

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

Примеры

Конфигурация Google Таблиц:

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

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

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 Таблиц с диапазоном (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 ds. alias .connector
Необязательный. Установите looker для соединителя Looker .

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

Пример

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

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 ds. alias .connector
Необязательный. Установите значение searchConsole для коннектора Search Console .

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

Пример

Конфигурация Search Console для свойства префикса URL :

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 на замену или обновление конфигурации источника данных.

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

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

Используйте пустой отчет или отчет по умолчанию

Чтобы использовать пустой отчет или отчет по умолчанию, настройте Linking 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.             Идентификатор отчета выделен.
Найдите идентификатор отчета в URL-адресе отчета.

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

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

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

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

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

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

Тип разъема

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

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

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

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

Диалоговое окно отладки

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

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

Разрешения

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

Обновление против замены

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

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

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

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

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

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

Например, если во время создания шаблона отчета Looker Studio идентифицирует определенное поле источника данных как тип Number , а вы меняете его на тип Year , это изменение конфигурации поля теперь является частью источника данных шаблона. Для любой диаграммы в шаблоне отчета, в которой используется исправленное поле, будет указан год , а если диаграмма основана на времени, иначе она может не отображаться. Если Linking API используется для предоставления новой конфигурации источника данных, которая дает точно такие же поля, в зависимости от значения refreshFields есть два результата:

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

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

Обратная связь и поддержка

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

Журнал изменений

06.06.2023

  • Добавлены параметры отчета r.measurementId и r.keepMeasurementId для настройки настройки отчета о измерениях Google Analytics .
  • Добавлен ds.keepDatasourceName для управления повторным использованием имени источника данных шаблона.
  • Добавлен раздел встроенного отчета .
  • BigQuery Connector
    • Добавлен sqlReplace . Позволяет указать строки шаблона и замены для обновления SQL -запроса источника данных шаблона.

2023-05-22

2022-11-21

2022-11-14

15.06.2022

  • Вне бета
    • Интеграционный API был переименован для связывания API .
    • Связывание API не бета.
  • Добавлен параметр управления pageId чтобы позволить связывать на конкретную страницу отчета.
  • Добавлен параметр управления mode , чтобы установить состояние отчета для просмотра или редактирования режима на загрузке.
  • Конфигурации источников данных теперь могут быть заменены полностью или частично обновлены. Такое поведение определяется тем, устанавливается ли параметр ds.connector . См. Заменить обновление VS для деталей.
  • В настоящее время используется шаблон по умолчанию, если шаблон отчета не предоставляется с использованием параметра c.reportId .
  • Добавлены параметр источника данных ds.refreshFields . Это позволяет вам контролировать, обновляются ли поля источника данных при загрузке конфигурации источника данных.
  • BigQuery Connector
    • projectId не требуется, когда type установлен на CUSTOM_QUERY .
    • Когда billingProjectId не будет установлен, проект биллинга будет отстранен от projectId или проекта запрашиваемой таблицы.
    • Добавлена ​​поддержка для даты распределенных таблиц. Установите параметр isPartitioned в true , чтобы использовать поле разделения в качестве измерения диапазона дат.
    • Добавлена ​​поддержка для запроса даты разбитых таблиц с использованием символа подстановочного знака или суффикса таблицы YYYYMMDD .
    • Добавлена ​​поддержка для запроса Google Analytics, Firebase Analytics или Crashlytics Tables и выбора шаблона полей.
  • Google Таблицы
    • hasHeader по умолчанию в true , в соответствии с по умолчанию веб -интерфейса.
    • includeHiddenAndFilteredCell в себя раздел includeHiddenCells и
    • includeFilteredCells . Оба теперь по true в соответствии с по умолчанию веб -интерфейса.
  • Поиск консоли разъем
    • Переименован параметр propertyType в searchType .
  • Обследование разъема
    • surveyId теперь принимает единый идентификатор опроса или отдельный список идентификаторов опроса.

16 декабря 2021 г.

  • Первоначальный выпуск интеграционного API.
    • Поддерживает ссылку на существующий отчет и установление имени отчета.
    • Можно настроить несколько источников данных, и каждое имя источника данных может быть установлено.
    • Поддержка следующих типов разъемов: BigQuery, Cloud Spanner, Google Analytics, Google Cloud Storage, Google Sheets, Google Surveys, консоль поиска.