מעבר ל-Google Analytics Admin API v1

עדיין יש תמיכה בערוצי אלפא ובטא של ה-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

שימוש בספריית לקוח

התקן ספריית לקוח

אם אתם משתמשים בספריית לקוח, עליכם להתקין את ספריית הלקוח של Admin API v1 לשפת התכנות שלכם.

Java

מדריך ההתקנה של ספריית הלקוח של Java

Python

מדריך ההתקנה של ספריית הלקוח של Python

Node.js

מדריך ההתקנה של ספריית הלקוח של Node.js

‎.NET

מדריך ההתקנה של ספריית הלקוח.NET

PHP

מדריך ההתקנה של ספריית הלקוח של 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, עדיין תוכלו להשתמש בפרטי הכניסה שלכם.

עליכם להשתמש במסמך הגילוי והנקודת הקצה (endpoint) החדש של 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 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.

בקשה ל-Admin 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 בגרסה 3

GET https://analytics.googleapis.com/analytics/v3/management/accountSummaries?key=[YOUR_API_KEY]

תגובת Management 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

google-analytics-admin/account_summaries_list.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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()


account_summaries_list.py

הצגת רשימה של החשבונות

השיטה accounts.list של Admin API v1 מחזירה את כל החשבונות שאליהם מבצע הקריאה החוזרת, בדומה ל-שיטת accounts.list של Management API v3.

בקשה ל-Admin 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 בגרסה 3

GET https://analytics.googleapis.com/analytics/v3/management/accounts?key=[YOUR_API_KEY]

תגובת Management 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

google-analytics-admin/accounts_list.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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)


accounts_list.py

ניהול נכסים

הצגת רשימה של מאפיינים

השיטה properties.list של Admin API v1 מחזירה את כל נכסי Google Analytics 4 שאליהם מבצע הקריאה החוזרת, בדומה לשיטה webproperties.list של Management API v3 שמחזירה את כל נכסי Universal Analytics הנגישים.

מכיוון שהשדה websiteUrl לא קיים יותר ברמת הנכס ב-Google Analytics 4, השתמשו ב-properties.dataStreams/list כדי להציג רשימה של כל מקורות הנתונים המשויכים לנכס ולחפש את השדה defaultUri כדי לאחזר את כתובת האתר המשויכת למקור נתונים.

שימו לב לפרמטר filter בכתובת ה-URL של הבקשה properties.list. ערך הפרמטר מכיל ביטוי לסינון התוצאות של הבקשה, ואפשר להשתמש בו כדי להציג רשימה של הנכסים שמשויכים למספר החשבון הנתון ב-Google Analytics או לפרויקט Firebase המקושר.

בקשה ל-Admin 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 בגרסה 3

GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]

תגובת Management 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

google-analytics-admin/properties_list.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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_list.py

אחזור של נכס

השיטה properties.get של Admin API v1 מחזירה את המידע על נכס Google Analytics 4, בדומה לשיטה webproperties.get של Management API v3.

שימו לב ששיטת properties.get ב-Admin API תומכת רק בנכסי Google Analytics 4.

בקשה ל-Admin 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 בגרסה 3

GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]

תגובת Management 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

google-analytics-admin/properties_get.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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_get.py

יצירת נכס

השיטה properties.create של Admin API v1 יוצרת נכס Google Analytics 4 חדש, בדומה לשיטה webproperties.insert של Management API v3.

בקשה ל-Admin 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 בגרסה 3

POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]

{
  "name": "Test",
  "websiteUrl": "YOUR-WEBSITE-URL"
}

תגובת Management 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

google-analytics-admin/properties_create.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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_create.py

עדכון/תיקון של מאפיין

השיטה properties.patch של Admin API v1 מעדכנת את ההגדרות של נכס Google Analytics 4, בדומה לשיטה webproperties.patch של Management API v3.

שימו לב לפרמטר updateMask בכתובת ה-URL של הבקשה, שמכיל את רשימת השדות שרוצים לעדכן, מופרדים בפסיקים. שדות שלא נמצאים ברשימה הזו לא יעודכנו. אם משתמשים בספריית לקוח, הפרמטר update_mask יהיה זמין כחלק מחתימת השיטה.

בקשה ל-Admin 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 בגרסה 3

PATCH https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]

{
  "name": "New Property Name",
  "industryVertical": "FINANCE"
}

תגובת Management 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

google-analytics-admin/properties_update.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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_)


properties_update.py

ניהול משתמשים

ב-Google Analytics Admin API מוטמע כרגע מודל של הרשאות משתמשים שדומה ל-Management API v3, אבל עם כמה הבדלים.

  1. ניהול הרשאות המשתמשים ב-Google Analytics Admin API מתבצע באמצעות המשאבים של החשבון AccessBinding והנכס AccessBinding במקום המשאבים AccountUserLink, WebPropertyUserLink וProfileUserLink בממשק ה-API לניהול גרסה 3.
  2. קישורי גישה לנכסים ב-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.

בקשה ל-Admin 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 בגרסה 3

GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]

תגובת Management 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

google-analytics-admin/accounts_access_bindings_list.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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_access_bindings_list.py

עדכון קישורי הגישה לחשבון

השיטה accounts.accessBindings.patch של ה-Admin API v1 מעדכנת את קישור הגישה לחשבון, בדומה לשיטה accountUserLinks.update של Management API v3.

בקשה ל-Admin 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 בגרסה 3

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"
    ]
  }
}

תגובת Management 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

google-analytics-admin/accounts_access_bindings_update.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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_access_bindings_update.py

יצירת קישורי גישה לחשבון

השיטה accounts.accessBindings.create של Admin API v1 יוצרת קישור גישה בחשבון, בדומה לשיטה accountUserLinks.insert של Management API v3.

בקשה ל-Admin 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 בגרסה 3

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"
    ]
  }
}

תגובת Management 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

google-analytics-admin/accounts_access_bindings_create.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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)


accounts_access_bindings_create.py

אצווה

ב-Admin API v1 אין תמיכה בקיבוץ קריאות מרובות של Google Analytics API באמצעות סוג התוכן מרובה חלקים/מעורב, בניגוד ל-Management API v3.

במקום זאת, קיבוץ הנתונים נתמך במפורש ברמת ה-API. בפונקציונליות הקיבוץ יש תמיכה בשיטות הבאות של Admin API v1:

קוד לדוגמה לקריאה ל-Admin API v1 באמצעות ספריות לקוח:

Python

google-analytics-admin/accounts_access_bindings_batch_create.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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()


accounts_access_bindings_batch_create.py

שינויים במכסת API

Admin API v1 כולל מכסות פחות מגבילות בהשוואה ל-Management API v3.

  • כברירת מחדל, מספר הבקשות ל-Admin API v1 מוגבל ל-600 בקשות לדקה לפרויקט GCP.
  • נכון לעכשיו, אין מכסת מגבלה יומית על מספר הקריאות ל-Admin API v1 בכל פרויקט GCP. שימו לב: המספר התיאורטי המקסימלי של בקשות ביום עדיין מוגבל על ידי מכסת מספר הבקשות לדקה.
  • הוסרה מגבלה נפרדת על מספר פעולות הכתיבה ביום.