Альфа- и бета-каналы API продолжают поддерживаться. Бета-канал содержит подмножество функций, доступных в альфа-версии, которые считаются стабильными и не претерпят существенных изменений в будущем. Новые функции будут добавлены в бета-версию по мере их разработки.
В этом документе представлены инструкции по переносу существующего кода из Google Analytics Management API v3 в Google Analytics Admin API v1 , а также дается краткий обзор ключевых различий между двумя API.
Почему мне нужно мигрировать?
Если вашему приложению необходимо создать или настроить ресурс Google Analytics 4, оно должно использовать Admin API v1. Management API v3 работает только с ресурсами Universal Analytics, а Admin API v1 — только с ресурсами Google Analytics 4.
Предварительные условия
Вам следует ознакомиться с основами Admin API v1, прочитав краткое руководство .
Начать
Для начала вы подготовите ресурс Google Analytics 4, включите Admin API v1, а затем настроите клиентскую библиотеку API, подходящую для вашей платформы.
Подготовьте ресурс Google Аналитики 4.
Прежде чем переносить код для поддержки Admin API v1, вам необходимо перенести свой веб-сайт на использование ресурса Google Analytics 4 .
Включить API
Нажмите эту кнопку, чтобы автоматически включить Admin API v1 в выбранном вами проекте Google Cloud.
Включите API администратора Google Analytics.Используйте клиентскую библиотеку
Установить клиентскую библиотеку
Если вы используете клиентскую библиотеку, вам необходимо установить клиентскую библиотеку Admin API v1 для вашего языка программирования.
Джава
Питон
Node.js
.СЕТЬ
PHP
Идти
go get google.golang.org/genproto/googleapis/analytics/admin/v1alpha
Инициализировать клиентскую библиотеку
Клиентские библиотеки Admin API v1 созданы для того, чтобы вы могли быстро приступить к работе. По умолчанию клиентские библиотеки пытаются автоматически найти учетные данные вашей сервисной учетной записи .
Простой способ предоставить учетные данные учетной записи службы — установить переменную среды GOOGLE_APPLICATION_CREDENTIALS . Клиент API будет использовать значение этой переменной для поиска файла JSON ключа учетной записи службы.
Например, вы можете установить учетные данные учетной записи службы, выполнив следующую команду и указав путь к файлу JSON учетной записи службы:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Ниже приведены фрагменты кода, которые обычно используются для инициализации клиентских библиотек Admin API v1.
Джава
try (AnalyticsAdminServiceClient analyticsAdmin = AnalyticsAdminServiceClient.create()) {
Питон
client = AlphaAnalyticsAdminClient()
.СЕТЬ
AlphaAnalyticsAdminClient client = AlphaAnalyticsAdminClient.Create();
PHP
$client = new AlphaAnalyticsAdminClient();
Node.js
// Imports the Google Analytics Data API client library.
const {AlphaAnalyticsAdminClient} = require('@google-analytics/admin');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsAdminClient = new AlphaAnalyticsAdminClient();
Вместо использования переменной среды также можно явно передать информацию об учетных данных экземпляру клиента API во время инициализации.
Если вы не используете клиентскую библиотеку
Если вы используете Management API v3 без клиентской библиотеки и хотите продолжать использовать Admin API v1, вы все равно можете использовать свои учетные данные.
Вам необходимо использовать новую конечную точку HTTP и документ обнаружения, предоставленный API администратора:
Если ваш код использует документ обнаружения , вам необходимо обновить его до документа обнаружения, предоставленного Admin API v1:
После обновления конечной точки вам необходимо будет ознакомиться с новой структурой запроса и концепциями API администратора, чтобы обновить запрос JSON.
Общие задачи
Управление аккаунтами
Admin API v1 предоставляет набор методов управления учетными записями и ресурсами Google Analytics, сравнимый с Management API v3. Кроме того, Admin API v1 предоставляет функции для предоставления , удаления и обновления учетных записей Google Analytics.
Методы управления ресурсами Admin API версии 1 поддерживают только ресурсы Google Аналитики 4.
Понятие представлений (профилей) отсутствует в Admin API v1.
Поскольку потоки данных были представлены в Google Analytics 4, определенная информация больше не присутствует на уровне ресурса. Например, поле
websiteUrlтеперь присутствует в сущностиDataStream, а не является частью объекта свойства.
Получение списка сводных данных по аккаунтам
Метод accountSummaries Admin API возвращает упрощенные сводки всех учетных записей, доступных вызывающей стороне, аналогично методу accountSummaries Management API v3 .
Важным отличием является то, что Admin API v1 возвращает только информацию о ресурсах Google Analytics 4, а ответы Management API v3 содержат данные о ресурсах, созданных с помощью Universal Analytics. Невозможно получить информацию об обоих типах свойств с помощью одного вызова.
Поскольку в Google Analytics 4 нет представлений (профилей), сводки аккаунтов, возвращаемые Admin API, не содержат информации о представлениях (профилях).
Сводные данные аккаунта Google Analytics 4 ограничены ресурсами и отображаемыми названиями аккаунтов/ресурсов, доступных текущему пользователю.
Используйте имена ресурсов, возвращаемые в полях account и property ответа сводки, чтобы получить полные данные конфигурации, вызывая методы account.get и property.get .
Запрос API администратора v1
GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries?key=[YOUR_API_KEY]
Ответ API администратора v1
{
"accountSummaries": [
{
"name": "accountSummaries/XXXXXX",
"account": "accounts/XXXXXX",
"displayName": "Test",
"propertySummaries": [
{
"property": "properties/XXXXXX",
"displayName": "Test App"
}
]
},
...
}
Запрос API управления v3
GET https://analytics.googleapis.com/analytics/v3/management/accountSummaries?key=[YOUR_API_KEY]
Ответ API управления v3
{
"kind": "analytics#accountSummaries",
"username": "XXXXXX",
"totalResults": 9,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX",
"kind": "analytics#accountSummary",
"name": "Test Account",
"webProperties": [
{
"kind": "analytics#webPropertySummary",
"id": "UA-XXXXXX",
"name": "Test Property",
"internalWebPropertyId": "XXXXXX",
"level": "STANDARD",
"websiteUrl": "XXXXXX",
"profiles": [
{
"kind": "analytics#profileSummary",
"id": "XXXXXX",
"name": "Test Profile",
"type": "WEB"
}
]
},
...
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
def list_account_summaries(transport: str = None) -> None:
"""
Prints summaries of all accounts accessible by the caller.
Args:
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_account_summaries()
print("Result:")
for account_summary in results:
print("-- Account --")
print(f"Resource name: {account_summary.name}")
print(f"Account name: {account_summary.account}")
print(f"Display name: {account_summary.display_name}")
print()
for property_summary in account_summary.property_summaries:
print("-- Property --")
print(f"Property resource name: {property_summary.property}")
print(f"Property display name: {property_summary.display_name}")
print()
Получение списка аккаунтов
accounts.list Admin API v1 возвращает все учетные записи, доступные вызывающей стороне, аналогично accounts.list Management API v3 .
Запрос API администратора v1
GET https://analyticsadmin.googleapis.com/v1beta/accounts?key=[YOUR_API_KEY]
Ответ API администратора v1
{
"accounts": [
{
"name": "accounts/XXXXXX",
"createTime": "2020-02-21T00:17:33.282Z",
"updateTime": "2021-01-07T02:47:57.386Z",
"displayName": "Test Account",
"regionCode": "US"
},
...
}
Запрос API управления v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts?key=[YOUR_API_KEY]
Ответ API управления v3
{
"kind": "analytics#accounts",
"username": "XXXXXX",
"totalResults": 9,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX",
"kind": "analytics#account",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "Test Account",
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"READ_AND_ANALYZE"
]
},
"created": "2020-02-21T00:17:33.282Z",
"updated": "2021-01-07T02:47:57.386Z",
"childLink": {
"type": "analytics#webproperties",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties"
}
},
...
}
Обратите внимание, что ответ Admin API v1 не включает информацию о действующих разрешениях пользователя, а также поле childLink , которое присутствовало в Management API v3.
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from accounts_get import print_account
def list_accounts(transport: str = None):
"""
Lists the Google Analytics accounts available to the current user.
Args:
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_accounts()
print("Result:")
for account in results:
print_account(account)
Управление свойствами
Список свойств
Метод properties.list Admin API v1 возвращает все свойства Google Analytics 4, доступные вызывающему объекту, аналогично методу webproperties.list Management API v3 , который возвращает все доступные свойства Universal Analytics.
Поскольку поле websiteUrl больше не присутствует на уровне ресурса в Google Analytics 4, используйте properties.dataStreams/list , чтобы перечислить все потоки данных, связанные с ресурсом, и найдите поле defaultUri , чтобы получить URL-адрес веб-сайта, связанный с потоком.
Обратите внимание на параметр filter в URL-адресе запроса properties.list . Значение параметра содержит выражение для фильтрации результатов запроса и может использоваться для вывода списка свойств, связанных с данным идентификатором аккаунта Google Analytics или со связанным проектом Firebase.
Запрос API администратора v1
GET https://analyticsadmin.googleapis.com/v1beta/properties?filter=parent:accounts/XXXXXX&key=[YOUR_API_KEY]
Ответ API администратора v1
{
"properties": [
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2020-10-29T04:02:49.124Z",
"updateTime": "2020-10-29T04:02:49.124Z",
"displayName": "Test Property",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
},
...
}
Запрос API управления v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]
Ответ API управления v3
{
"kind": "analytics#webproperties",
"username": "XXXXXX",
"totalResults": 33,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "UA-XXXXXX-1",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test Account",
"websiteUrl": "XXXXXX",
"level": "PREMIUM",
"profileCount": 4,
"industryVertical": "HEALTH",
"defaultProfileId": "XXXXXX",
"dataRetentionTtl": "INDEFINITE",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"READ_AND_ANALYZE"
]
},
"created": "2020-02-21T00:28:47.287Z",
"updated": "2021-01-27T21:39:22.704Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/profiles"
}
},
...
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import ListPropertiesRequest
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
list_properties(account_id)
def list_properties(account_id: str, transport: str = None):
"""
Lists Google Analytics 4 properties under the specified parent account
that are available to the current user.
Args:
account_id(str): The Google Analytics account ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_properties(
ListPropertiesRequest(filter=f"parent:accounts/{account_id}", show_deleted=True)
)
print("Result:")
for property_ in results:
print(property_)
print()
Получить недвижимость
Метод properties.get Admin API v1 возвращает информацию о ресурсе Google Analytics 4, аналогично методу webproperties.get Management API v3 .
Обратите внимание, что метод properties.get Admin API поддерживает только ресурсы Google Analytics 4.
Запрос API администратора v1
GET https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?key=[YOUR_API_KEY]
Ответ API администратора v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-04-30T21:32:49.804Z",
"updateTime": "2021-04-30T21:32:49.804Z",
"displayName": "Test Property",
"industryCategory": "FINANCE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Запрос API управления v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]
Ответ API управления v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test 2",
"websiteUrl": "YOUR-WEBSITE-URL",
"level": "STANDARD",
"profileCount": 0,
"industryVertical": "FINANCE",
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:41:39.219Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import IndustryCategory
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID (e.g. "123456") before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
get_property(property_id)
def get_property(property_id: str, transport: str = None):
"""
Retrieves the Google Analytics 4 property details.
Args:
property_id(str): The Google Analytics Property ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
property_ = client.get_property(name=f"properties/{property_id}")
print("Result:")
print_property(property_)
def print_property(property):
"""Prints the Google Analytics 4 property details."""
print(f"Resource name: {property.name}")
print(f"Parent: {property.parent}")
print(f"Display name: {property.display_name}")
print(f"Create time: {property.create_time}")
print(f"Update time: {property.update_time}")
# print(f"Delete time: {property.delete_time}")
# print(f"Expire time: {property.expire_time}")
if property.industry_category:
print(f"Industry category: {IndustryCategory(property.industry_category).name}")
print(f"Time zone: {property.time_zone}")
print(f"Currency code: {property.currency_code}")
Создать свойство
Метод properties.create Admin API v1 создает новый ресурс Google Analytics 4, аналогичный методу webproperties.insert Management API v3 .
Запрос API администратора v1
POST https://analyticsadmin.googleapis.com/v1beta/properties?key=[YOUR_API_KEY]
{
"displayName": "Test Property",
"industryCategory": "AUTOMOTIVE",
"currencyCode": "USD",
"timeZone": "America/Los_Angeles",
"parent": "accounts/XXXXXX"
}
Ответ API администратора v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-05-20T09:16:08.458Z",
"updateTime": "2021-05-20T09:16:08.458Z",
"displayName": "Test Property",
"industryCategory": "AUTOMOTIVE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Запрос API управления v3
POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]
{
"name": "Test",
"websiteUrl": "YOUR-WEBSITE-URL"
}
Ответ API управления v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test",
"websiteUrl": "YOUR-WEBSITE-URL",
"level": "STANDARD",
"profileCount": 0,
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:35:51.985Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import Property
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
create_property(account_id)
def create_property(account_id: str, transport: str = None):
"""
Creates a Google Analytics 4 property.
Args:
account_id(str): The Google Analytics Account ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
property_ = client.create_property(
property=Property(
parent=f"accounts/{account_id}",
currency_code="USD",
display_name="Test property",
industry_category="OTHER",
time_zone="America/Los_Angeles",
)
)
print("Result:")
print(property_)
Обновить/исправить свойство
Метод properties.patch Admin API v1 обновляет конфигурацию ресурса Google Analytics 4 аналогично методу webproperties.patch Management API v3 .
Обратите внимание на параметр updateMask в URL-адресе запроса, который содержит разделенный запятыми список полей, которые необходимо обновить. Поля, которых нет в этом списке, обновляться не будут. При использовании клиентской библиотеки параметр update_mask будет доступен как часть сигнатуры метода.
Запрос API администратора v1
PATCH https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?updateMask=displayName,industryCategory&key=[YOUR_API_KEY]
{
"displayName": "New Property Name",
"industryCategory": "FINANCE"
}
Ответ API администратора v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-04-30T21:32:49.804Z",
"updateTime": "2021-05-20T09:25:14.810Z",
"displayName": "New Property Name",
"industryCategory": "FINANCE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Запрос API управления v3
PATCH https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]
{
"name": "New Property Name",
"industryVertical": "FINANCE"
}
Ответ API управления v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "New Property Name",
"websiteUrl": "XXXXXX",
"level": "STANDARD",
"profileCount": 0,
"industryVertical": "FINANCE",
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:41:39.219Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import Property
from google.protobuf.field_mask_pb2 import FieldMask
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics property ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID (e.g. "123456") before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
update_property(property_id)
def update_property(property_id: str, transport: str = None):
"""
Updates the Google Analytics 4 property.
Args:
property_id(str): The Google Analytics Property ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
# This call updates the display name, industry category and time zone of the
# property, as indicated by the value of the `update_mask` field.
# The property to update is specified in the `name` field of the `Property`
# instance.
property_ = client.update_property(
property=Property(
name=f"properties/{property_id}",
display_name="This is an updated test property",
industry_category="GAMES",
time_zone="America/New_York",
),
update_mask=FieldMask(paths=["display_name", "time_zone", "industry_category"]),
)
print("Result:")
print(property_)
Управление пользователями
API администратора Google Analytics в настоящее время реализует модель разрешений пользователей, аналогичную Management API v3, но с некоторыми отличиями.
- Вы управляете разрешениями пользователей с помощью Google Analytics Admin API, используя ресурсы
AccessBindingучетной записи и свойстваAccessBindingвместо ресурсовAccountUserLink,WebPropertyUserLinkиProfileUserLinkв Management API v3. - Привязки доступа к ресурсам в Google Analytics Admin API не включают подразумеваемые разрешения или разрешения, унаследованные от привязок доступа к аккаунту. В Management API v3 каждая пользовательская ссылка содержала коллекцию
permissions.effective, включающую как подразумеваемые, так и унаследованные разрешения.
Сущность AccessBinding содержит пользователя (адрес электронной почты) и список ролей, предоставленных пользователю. Сущность AccessBinding можно создавать, обновлять или удалять.
Сопоставление имен ролей Admin API v1 и имен разрешений Management API v3 выглядит следующим образом:
| Роль API администратора v1 | Имя разрешения Management API v3 |
|---|---|
| предопределенные роли/просмотрщик | ЧИТАТЬ_И_АНАЛИЗИРОВАТЬ |
| предопределенные роли/аналитик | СОТРУДНИЧАТЬ |
| предопределенные роли/редактор | РЕДАКТИРОВАТЬ |
| предопределенные роли/администратор | УПРАВЛЕНИЕ ПОЛЬЗОВАТЕЛЯМИ |
Роли predefinedRoles/no-cost-data , predefinedRoles/no-revenue-data были введены в Admin API v1 и не имеют соответствующего сопоставления в Management API v3.
В этом руководстве показано, как управлять привязками доступа на уровне учетной записи. Чтобы управлять привязками доступа на уровне свойства, выполните тот же процесс, но используйте ресурсы и методы свойства AccessBinding вместо учетной записи AccessBinding .
Получение списка привязок доступа к учетной записи
accounts.accessBindings.list Admin API v1 перечисляет все привязки доступа к учетной записи, аналогично методу accountUserLinks.list Management API v3 .
Запрос API администратора v1
GET https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX
Ответ API администратора v1
{
"accessBindings": [
{
"name": "accounts/XXXXXX/accessBindings/XXXXXX",
"user": "XXXXXX",
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
]
}
Запрос API управления v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]
Ответ API управления v3
{
"kind": "analytics#entityUserLinks",
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX:XXXXXX",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:XXXXXX",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "XXXXXX",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
]
}
Пример кода для вызова Admin API с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
list_account_access_bindings(account_id)
def list_account_access_bindings(account_id: str, transport: str = None):
"""
Lists access bindings under the specified parent account.
Args:
account_id(str): The id of the account.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_access_bindings(parent=f"accounts/{account_id}")
print("Result:")
for access_binding in results:
print(access_binding)
print()
Обновить привязки доступа к учетной записи
accounts.accessBindings.patch Admin API v1 обновляет привязку доступа к учетной записи, аналогично методу accountUserLinks.update Management API v3 .
Запрос API администратора v1
PATCH https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX
{
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Ответ API администратора v1
{
"name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
"user": "USER-EMAIL",
"directRoles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Запрос API управления v3
PUT https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX%3A104236685715552897132?key=[YOUR_API_KEY]
{
"entity": {
"accountRef": {
"id": "XXXXXX"
}
},
"userRef": {
"email": "XXXXXX"
},
"permissions": {
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Ответ API управления v3
{
"id": "XXXXXX:104236685715552897132",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:104236685715552897132",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "104236685715552897132",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import AccessBinding
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics property ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with your Google Analytics
# account access binding ID (e.g. "123456") before running the sample.
account_access_binding_id = "YOUR-ACCOUNT-ACCESS-BINDING-ID"
update_account_access_binding(account_id, account_access_binding_id)
def update_account_access_binding(
account_id: str, account_access_binding_id: str, transport: str = None
):
"""
Updates the account access binding.
Args:
account_id(str): The Google Analytics Account ID.
account_access_binding_id(str): Google Analytics account access binding ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
# This call updates the roles of the access binding. The access binding to
# update is specified in the `name` field of the `AccessBinding` instance.
access_binding = client.update_access_binding(
access_binding=AccessBinding(
name=f"accounts/{account_id}/accessBindings/{account_access_binding_id}",
roles=["predefinedRoles/collaborate"],
),
)
print("Result:")
print(access_binding)
Создание привязок доступа к учетной записи
Метод accounts.accessBindings.create Admin API v1 создает привязку доступа в учетной записи, аналогично методу accountUserLinks.insert Management API v3 .
Запрос API администратора v1
POST https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings
{
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
],
"user": "USER-EMAIL"
}
Ответ API администратора v1
{
"name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
"user": "USER-EMAIL",
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Запрос API управления v3
POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]
{
"entity": {
"accountRef": {
"id": "XXXXXX"
}
},
"userRef": {
"email": "XXXXXX"
},
"permissions": {
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Ответ API управления v3
{
"id": "XXXXXX:114236685715552897132",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:114236685715552897132",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "114236685715552897132",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
AccessBinding,
CreateAccessBindingRequest,
)
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with an email address of the user to
# link. This user will be given access to your account after running the
# sample.
email_address = "TEST-EMAIL-ADDRESS"
create_account_access_binding(account_id, email_address)
def create_account_access_binding(
account_id: str, email_address: str, transport: str = None
):
"""
Creates a access binding for the account.
Args:
account_id(str): The Google Analytics Account ID.
email_address(str): Email address of the access binding user.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
access_binding = client.create_access_binding(
CreateAccessBindingRequest(
parent=f"accounts/{account_id}",
access_binding=AccessBinding(
user=email_address, roles=["predefinedRoles/read"]
),
)
)
print("Result:")
print(access_binding)
Пакетирование
Admin API v1 не поддерживает пакетную обработку нескольких вызовов Google Analytics API с использованием многочастного/смешанного типа контента, в отличие от Management API v3 .
Вместо этого пакетная обработка поддерживается явно на уровне API. Следующие методы Admin API v1 поддерживают функцию пакетной обработки:
Пример кода для вызова Admin API v1 с использованием клиентских библиотек:
Питон
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
AccessBinding,
BatchCreateAccessBindingsRequest,
CreateAccessBindingRequest,
)
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with an email address of the user to
# link. This user will be given access to your account after running the
# sample.
email_address = "TEST-EMAIL-ADDRESS"
batch_create_account_access_binding(account_id, email_address)
def batch_create_account_access_binding(
account_id: str, email_address: str, transport: str = None
):
"""
Creates a access binding for the account using a batch call.
Args:
account_id(str): The Google Analytics Account ID.
email_address(str): Email address of the access binding user.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
response = client.batch_create_access_bindings(
BatchCreateAccessBindingsRequest(
parent=f"accounts/{account_id}",
requests=[
CreateAccessBindingRequest(
access_binding=AccessBinding(
user=email_address,
roles=["predefinedRoles/read"],
)
)
],
)
)
print("Result:")
for access_binding in response.access_bindings:
print(access_binding)
print()
Изменения квот API
Admin API v1 вводит менее строгие квоты по сравнению с Management API v3.
- По умолчанию для проекта GCP количество запросов к Admin API v1 ограничено 600 запросами в минуту .
- В настоящее время не существует дневной лимитной квоты на количество вызовов Admin API v1 для каждого проекта GCP . Обратите внимание, что теоретическое максимальное количество запросов в день по-прежнему ограничено квотой запросов в минуту .
- Снят отдельный лимит на количество операций записи в день.