ระบบยังรองรับทั้งเวอร์ชันอัลฟ่าและเบต้าของ 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 Analytics 4
ก่อนที่จะย้ายโค้ดเพื่อรองรับ Admin API v1 คุณต้องย้ายข้อมูลเว็บไซต์ไปใช้พร็อพเพอร์ตี้ Google Analytics 4
เปิดใช้ API
คลิกปุ่มนี้เพื่อเปิดใช้ Admin API v1 ในโปรเจ็กต์ Google Cloud ที่คุณเลือกโดยอัตโนมัติ
เปิดใช้ Google Analytics Admin APIใช้ไลบรารีของไคลเอ็นต์
ติดตั้งไลบรารีของไคลเอ็นต์
หากใช้ไลบรารีของไคลเอ็นต์ คุณต้องติดตั้งไลบรารีของไคลเอ็นต์ API เวอร์ชัน 1 ของ Admin API สำหรับภาษาโปรแกรมของคุณ
Java
Python
Node.js
.NET
PHP
Go
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
Java
try (AnalyticsAdminServiceClient analyticsAdmin = AnalyticsAdminServiceClient.create()) {
Python
client = AlphaAnalyticsAdminClient()
.NET
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 และเอกสารการค้นพบใหม่จาก Admin API ดังนี้
หากโค้ดใช้ประโยชน์จากเอกสาร Discovery คุณจะต้องอัปเดตโค้ดลงในเอกสารการค้นพบจาก Admin API v1 ดังนี้
หลังจากอัปเดตปลายทางแล้ว คุณจะต้องทำความคุ้นเคยกับโครงสร้างคำขอและแนวคิดใหม่ของ Admin API เพื่ออัปเดตการค้นหา JSON
งานทั่วไป
จัดการบัญชี
Admin API v1 ให้ชุดบัญชี Google Analytics และวิธีการจัดการพร็อพเพอร์ตี้ที่เทียบได้กับ Management API v3 นอกจากนี้ Admin API v1 ยังมีฟังก์ชันการจัดสรร ลบ อัปเดต บัญชี Google Analytics
เมธอดการจัดการพร็อพเพอร์ตี้ Admin API v1 รองรับเฉพาะพร็อพเพอร์ตี้ Google Analytics 4 เท่านั้น
ข้อมูลพร็อพเพอร์ตี้ (โปรไฟล์) จะไม่ปรากฏใน Admin API เวอร์ชัน 1
เนื่องจากมีการเริ่มใช้สตรีมข้อมูลใน Google Analytics 4 ข้อมูลบางอย่างจึงจะไม่แสดงในระดับพร็อพเพอร์ตี้อีกต่อไป เช่น ตอนนี้ช่อง
websiteUrlจะปรากฏในเอนทิตีDataStreamแทนที่จะเป็นส่วนหนึ่งของออบเจ็กต์พร็อพเพอร์ตี้
แสดงรายการสรุปบัญชี
เมธอด accountSummaries ของ Admin API จะแสดงผลสรุปสั้นๆ เกี่ยวกับบัญชีทั้งหมดที่ผู้โทรเข้าถึงได้ ซึ่งคล้ายกับเมธอด accountSummaries ของ Management API v3
ความแตกต่างที่สำคัญคือ Admin API v1 จะแสดงเฉพาะข้อมูลเกี่ยวกับพร็อพเพอร์ตี้ Google Analytics 4 เท่านั้น ขณะที่การตอบกลับของ Management API v3 มีข้อมูลเกี่ยวกับพร็อพเพอร์ตี้ที่สร้างด้วย Universal Analytics ไม่สามารถดึงข้อมูลเกี่ยวกับพร็อพเพอร์ตี้ทั้ง 2 ประเภทโดยใช้การเรียกครั้งเดียว
เนื่องจากไม่มีข้อมูลพร็อพเพอร์ตี้ (โปรไฟล์) ใน 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]
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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]
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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]
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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]
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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"
}
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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"
}
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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_)
จัดการผู้ใช้
ปัจจุบัน Google Analytics Admin API ใช้โมเดลสิทธิ์ของผู้ใช้ที่คล้ายกับ 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 มีดังนี้
| บทบาท Admin API v1 | ชื่อสิทธิ์ Management API v3 |
|---|---|
| บทบาท/ผู้ดูที่กำหนดไว้ล่วงหน้า | READ_AND_ANALYZE |
| บทบาท/นักวิเคราะห์ที่กำหนดไว้ล่วงหน้า | ทำงานร่วมกัน |
| บทบาท/เครื่องมือแก้ไขที่กำหนดไว้ล่วงหน้า | แก้ไข |
| บทบาท/ผู้ดูแลระบบที่กำหนดไว้ล่วงหน้า | MANAGE_USERS |
มีการใช้บทบาท 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
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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"
]
}
การตอบกลับของ 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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"
}
การตอบกลับของ Admin 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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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 โดยใช้ไลบรารีของไคลเอ็นต์
Python
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
- จำนวนคำขอที่ส่งไปยัง Admin API v1 จำกัดอัตราไว้ที่ 600 คำขอต่อนาทีโดยค่าเริ่มต้นสำหรับโปรเจ็กต์ GCP
- ปัจจุบันไม่มีขีดจำกัดโควต้ารายวันสำหรับจำนวนการเรียก Admin API v1 ต่อโปรเจ็กต์ GCP โปรดทราบว่าจำนวนคำขอสูงสุดทางทฤษฎีต่อวันยังถูกจำกัดโดยโควต้าคำขอต่อนาที
- เราได้นำข้อจำกัดแยกต่างหากสำหรับจำนวนการดำเนินการเขียนต่อวันออกแล้ว