1. 理解问题：API响应对象的挑战
在使用google analytics admin api（或其他基于grpc或protobuf的api）时，通常会遇到其响应对象并非标准的python字典或列表，也无法直接进行json序列化。例如，admin_v1beta.analyticsadminserviceclient().list_custom_dimensions() 方法返回的是一个 listcustomdimensionspager 类型的对象。
from google.analytics.admin import admin_v1beta
import pandas as pd
import json
def get_custom_dimensions_raw(property_filter):
"""
获取Google Analytics自定义维度原始API响应。
"""
client = admin_v1beta.AnalyticsAdminServiceClient()
request = admin_v1beta.ListCustomDimensionsRequest(
parent=property_filter
)
return client.list_custom_dimensions(request=request)
# 示例调用
# ga4_custom_dimensions = get_custom_dimensions_raw("properties/YOUR_PROPERTY_ID")
# print(type(ga4_custom_dimensions))
# <class 'google.analytics.admin_v1beta.services.analytics_admin_service.pagers.ListCustomDimensionsPager'>直接尝试将此类对象转换为JSON（如 json.dumps(ga4_custom_dimensions.__dict__) 或 json.dumps(vars(ga4_custom_dimensions))）会导致 TypeError: Object of type _GapicCallable is not JSON serializable。同样，pd.json_normalize() 或直接的字典式索引（如 ga4_custom_dimensions['custom_dimensions']）也无法奏效，因为 ListCustomDimensionsPager 对象不支持这些操作。
问题的核心在于，ListCustomDimensionsPager 是一个迭代器，其内部的每个元素是 CustomDimension 类型的protobuf消息对象，虽然其 __dict__ 属性包含了数据，但格式并非标准的JSON字符串，且包含内部私有属性和非标准键值对表示，导致无法直接解析。
2. 解决方案：迭代、字符串格式化与JSON解析
解决此问题的方法是迭代 ListCustomDimensionsPager 对象，对每个 CustomDimension 消息对象进行处理。由于直接序列化失败，我们可以利用其 __dict__ 属性的字符串表示，通过一系列字符串替换操作将其转换为有效的JSON格式，然后使用 json.loads() 解析，最终构建Pandas DataFrame。
以下是详细的步骤和代码实现：
2.1 核心处理函数
from google.analytics.admin import admin_v1beta
import pandas as pd
import json
def get_custom_dimensions_dataframe(property_filter):
"""
从Google Analytics Admin API获取自定义维度，并将其转换为Pandas DataFrame。
参数:
property_filter (str): GA4媒体资源ID，格式为 "properties/YOUR_PROPERTY_ID"。
返回:
pd.DataFrame: 包含自定义维度数据的DataFrame。
"""
client = admin_v1beta.AnalyticsAdminServiceClient()
request = admin_v1beta.ListCustomDimensionsRequest(
parent=property_filter
)
# 获取原始API响应，这是一个可迭代的Pager对象
full_response_pager = client.list_custom_dimensions(request=request)
df_list = []
# 遍历Pager中的每个CustomDimension对象
for response_item in full_response_pager:
# 1. 获取对象的内部字典表示
step1 = response_item.__dict__
# 2. 将字典转换为字符串，这是进行字符串替换的基础
step2 = str(step1)
# 3. 执行一系列字符串替换，将非标准的键值对格式转换为有效的JSON格式
# 原始字符串中键没有引号，值如果是字符串也没有引号，布尔值/枚举值也需要特殊处理。
# 移除内部的'_pb'属性，因为它不是我们关心的数据，且可能干扰JSON解析。
step3 = step2.replace(': name:', ': "name" :')
step4 = step3.replace('parameter_name:', ', "parameter_name" :')
step5 = step4.replace('display_name:', ', "display_name" :')
step6 = step5.replace('description:', ', "description" :')
step7 = step6.replace('scope:', ', "scope" :')
step8 = step7.replace('disallow_ads_personalization: true', ', "disallow_ads_personalization" : "true"')
step9 = step8.replace("'_pb': ", "") # 移除内部私有属性
step10 = step9.replace(' : EVENT', ' : "EVENT"') # 为枚举值添加引号
step11 = step10.replace(' : USER', ' : "USER"') # 为枚举值添加引号
# 4. 处理Unicode转义字符：
# 有时字符串中可能包含形如 '\xXX' 的转义字符，需要先编码为UTF-8，再解码为Unicode字符串。
step12 = step11.encode('utf-8').decode('unicode_escape')
# 5. 将处理后的字符串加载为JSON对象
# 注意：此时的字符串应该是一个有效的JSON格式的字典字符串
try:
step13 = json.loads(step12)
df_list.append(step13)
except json.JSONDecodeError as e:
print(f"JSON解析错误: {e}")
print(f"问题字符串: {step12}")
# 可以选择跳过此项或记录错误
continue
# 6. 从JSON对象列表创建Pandas DataFrame
return pd.DataFrame(df_list)2.2 使用示例
# 替换为您的GA4媒体资源ID
GA4_PROPERTY_ID = "YOUR_PROPERTY_ID"
# 调用函数获取DataFrame
custom_dimension_df = get_custom_dimensions_dataframe(f"properties/{GA4_PROPERTY_ID}")
# 打印DataFrame的前几行和信息
print(custom_dimension_df.head())
print("\nDataFrame信息:")
custom_dimension_df.info()
# 示例：保存到CSV文件
# custom_dimension_df.to_csv("ga4_custom_dimensions.csv", index=False, encoding="utf-8")3. 注意事项与总结
- 字符串替换的局限性： 这种通过字符串替换来构造JSON的方法虽然有效，但并不“优雅”，且对原始字符串的格式高度敏感。如果API响应的内部字符串表示发生变化，可能需要调整 str.replace() 步骤。
- 字段完整性： 上述代码仅处理了 name, parameter_name, display_name, description, scope, disallow_ads_personalization 等字段。如果 CustomDimension 对象包含其他字段，且您需要将其纳入DataFrame，则需要添加相应的 str.replace() 规则。
- 错误处理： 增加了 try-except 块来捕获 json.JSONDecodeError，这在处理API响应时是良好的实践，以防某个响应项的字符串格式未能被完全纠正。
- 替代方案（若API支持）： 理想情况下，API响应对象会提供 .to_dict() 或 .to_json() 等方法，直接将对象转换为Python字典或JSON字符串。在没有这些便捷方法时，上述字符串替换方案提供了一种可行的“黑箱”处理方式。
- 性能考量： 对于大量数据，字符串替换操作可能相对耗时。然而，对于大多数Google Analytics Admin API的使用场景，自定义维度数量通常有限，因此性能影响可以接受。
通过上述方法，您可以成功地将Google Analytics Admin API返回的复杂响应对象转换为易于分析和处理的Pandas DataFrame，从而更好地利用您的GA4数据。
