نقل البيانات إلى الإصدار 1 من Admin API في "إحصاءات Google"

وما زال بإمكانك استخدام كل من قناة الإصدار الأولي والقناة التجريبية الخاصة بواجهة برمجة التطبيقات. تحتوي القناة التجريبية على مجموعة فرعية من الميزات المتاحة في الإصدار الأولي والتي تُعتبر ثابتة ولا يُتوقع أن تخضع لتغيير كبير في المستقبل. ستتم إضافة ميزات جديدة إلى الإصدار التجريبي فور اكتمالها.

يقدّم هذا المستند تعليمات حول كيفية نقل الرمز الحالي من الإصدار 3 من Google Analytics Management API إلى الإصدار 1 من Google Analytics Admin API، كما يقدّم نظرة عامة مختصرة على الاختلافات الرئيسية بين واجهتَي برمجة التطبيقات.

لماذا عليّ نقل البيانات؟

إذا كان تطبيقك بحاجة إلى إنشاء أو ضبط موقع على "إحصاءات Google 4"، يجب أن يستخدم الإصدار 1 من Admin API. لا يعمل الإصدار 3 من Management API إلّا مع مواقع Universal Analytics، في حين يعمل الإصدار 1 من Admin API فقط مع مواقع "إحصاءات Google 4".

المتطلبات الأساسية

يجب التعرّف على أساسيات الإصدار 1 من Admin API من خلال قراءة دليل البدء السريع.

بدء

للبدء، عليك إعداد موقع على "إحصاءات Google 4"، وتفعيل الإصدار الأول من واجهة برمجة التطبيقات Admin API، ثم إعداد مكتبة عملاء خاصة بواجهة برمجة التطبيقات مناسبة لنظامك الأساسي.

إعداد موقع على "إحصاءات Google 4"

قبل نقل الرمز للتوافق مع الإصدار 1 من Admin API، عليك نقل موقعك الإلكتروني لاستخدام موقع على "إحصاءات Google 4".

تفعيل واجهة برمجة التطبيقات

انقر على هذا الزر لتفعيل الإصدار 1 من Admin API تلقائيًا في مشروع Google Cloud الذي اخترته.

تفعيل Google Analytics Admin API

استخدام مكتبة عملاء

تثبيت مكتبة برامج

إذا كنت تستخدم مكتبة برامج، عليك تثبيت الإصدار الأول من مكتبة برامج واجهة برمجة التطبيقات Admin API للغة البرمجة.

Java

دليل تثبيت مكتبة عملاء Java

Python

دليل تثبيت مكتبة برامج Python

Node.js

دليل تثبيت مكتبة عملاء Node.js

NET.

دليل تثبيت مكتبة برامج.NET

PHP

دليل تثبيت مكتبة برامج PHP

البدء

go get google.golang.org/genproto/googleapis/analytics/admin/v1alpha

إعداد مكتبة برامج

تم تصميم مكتبات عملاء الإصدار 1 من Admin API لمساعدتك في البدء بسرعة. تحاول مكتبات العملاء العثور تلقائيًا على بيانات اعتماد حساب الخدمة.

تتوفّر طريقة سهلة لتوفير بيانات اعتماد حساب الخدمة من خلال ضبط متغيّر بيئة GOOGLE_APPLICATION_CREDENTIALS، وسيستخدم عميل واجهة برمجة التطبيقات قيمة هذا المتغيّر للعثور على ملف JSON لمفتاح حساب الخدمة.

على سبيل المثال، يمكنك ضبط بيانات اعتماد حساب الخدمة من خلال تنفيذ الأمر التالي واستخدام المسار إلى ملف JSON لحساب الخدمة:

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

وفي ما يلي مقتطفات الرموز التي يشيع استخدامها لإعداد مكتبات برامج الإصدار 1 من Admin API.

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();

بدلاً من استخدام متغير بيئة، من الممكن أيضًا تمرير معلومات بيانات الاعتماد إلى مثيل عميل واجهة برمجة التطبيقات بشكل صريح أثناء التهيئة.

في حال عدم استخدام مكتبة برامج

إذا كنت تستخدم الإصدار 3 من Management API بدون مكتبة برامج وأردت مواصلة استخدام الإصدار 1 من Admin API، لا يزال بإمكانك استخدام بيانات الاعتماد الخاصة بك.

عليك استخدام مستند نقطة نهاية HTTP الجديد واكتشافه الذي تم تقديمه من خلال واجهة برمجة تطبيقات المشرف:

إذا كانت الرموز البرمجية تستفيد من مستند Discovery، عليك تعديله إلى مستند Discovery المقدَّم من خلال الإصدار 1 من Admin API:

بعد تحديث نقطة النهاية، ستحتاج إلى التعرّف على بنية الطلب الجديدة ومفاهيم واجهة برمجة تطبيقات Admin API لتعديل طلب بحث JSON.

المهام الشائعة

إدارة الحسابات

يوفّر الإصدار 1 من Admin API مجموعة من طرق إدارة الحسابات والمواقع على "إحصاءات Google" يمكن مقارنتها بالإصدار 3 من Management API. بالإضافة إلى ذلك، يقدّم الإصدار 1 من Admin API وظائف توفير المتطلبات اللازمة وحذف وتحديث حسابات "إحصاءات Google".

  • تكون مواقع "إحصاءات Google 4" فقط متوافقة مع طرق إدارة المواقع في الإصدار 1 من Admin API.

  • لا تتوفر مفهوم الملفات الشخصية في الإصدار 1 من Admin API.

  • بما أنّه تم تقديم مصادر البيانات في "إحصاءات Google 4"، لم تعُد بعض المعلومات متوفّرة على مستوى الموقع. على سبيل المثال، يتوفّر الحقل websiteUrl الآن في كيان DataStream بدلاً من كونه جزءًا من كائن السمة.

سرد ملخّصات الحسابات

تعرض طريقة accountSummaries في Admin API ملخّصات بسيطة لجميع الحسابات التي يمكن للمتصل الوصول إليها، على غرار طريقة accountSummaries من Management API في الإصدار 3 من Management API.

ومن الاختلافات المهمة أنّ الإصدار 1 من Admin API لا يعرض سوى معلومات عن مواقع "إحصاءات Google 4"، في حين أنّ استجابات الإصدار 3 من Management API تحتوي على بيانات عن المواقع التي تم إنشاؤها باستخدام Universal Analytics. لا يمكن استرداد المعلومات حول كلا نوعَي المواقع باستخدام استدعاء واحد.

نظرًا لعدم توفّر ملفات شخصية (ملفات شخصية) في "إحصاءات Google 4"، لا تحتوي ملخّصات الحسابات التي تعرضها واجهة برمجة التطبيقات Admin API على معلومات الملفات الشخصية.

تقتصر بيانات ملخّص حساب "إحصاءات Google 4" على الموارد والأسماء المعروضة للحسابات/المواقع المتاحة للمستخدم الحالي.

استخدِم أسماء الموارد التي يتم عرضها في الحقول account وproperty من استجابة الملخّصات لاسترداد بيانات الإعدادات الكاملة من خلال استدعاء طريقتَي account.get وproperty.get.

طلب الإصدار 1 من Admin API

GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries?key=[YOUR_API_KEY]

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

{
  "accountSummaries": [
    {
      "name": "accountSummaries/XXXXXX",
      "account": "accounts/XXXXXX",
      "displayName": "Test",
      "propertySummaries": [
        {
          "property": "properties/XXXXXX",
          "displayName": "Test App"
        }
      ]
    },
    ...
}

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

{
  "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"
            }
          ]
        },
        ...
}

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 في الإصدار 1 من Admin API جميع الحسابات التي يمكن للمتصل الوصول إليها، بطريقة تشبه طريقة accounts.list في الإصدار 3 من Management API.

طلب الإصدار 1 من Admin API

GET https://analyticsadmin.googleapis.com/v1beta/accounts?key=[YOUR_API_KEY]

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

{
  "accounts": [
    {
      "name": "accounts/XXXXXX",
      "createTime": "2020-02-21T00:17:33.282Z",
      "updateTime": "2021-01-07T02:47:57.386Z",
      "displayName": "Test Account",
      "regionCode": "US"
    },
  ...
}

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

{
  "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"
      }
    },
    ...
}

تجدر الإشارة إلى أنّ الإصدار 1 من واجهة برمجة تطبيقات المشرف لا يتضمن معلومات حول أذونات المستخدم الفعّالة، ولا حقل childLink الذي كان متوفرًا في الإصدار 3 من واجهة برمجة تطبيقات الإدارة.

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 في الإصدار 1 من Admin API جميع مواقع "إحصاءات Google 4" التي يمكن للطالب الوصول إليها، وهي تشبه طريقة webproperties.list من واجهة برمجة التطبيقات Management API الإصدار 3 والتي تعرض جميع مواقع Universal Analytics التي يمكن الوصول إليها.

بما أنّ الحقل websiteUrl لم يعُد متوفّرًا على مستوى الموقع في "إحصاءات Google 4"، استخدِم properties.dataStreams/list لإدراج جميع مصادر البيانات المرتبطة بالموقع والبحث في حقل defaultUri لاسترداد عنوان URL للموقع الإلكتروني المرتبط بمصدر بيانات.

تحقَّق من المَعلمة filter في عنوان URL لطلب properties.list. تحتوي قيمة المعلَمة على تعبير لفلترة نتائج الطلب، ويمكن استخدامها لسرد المواقع المرتبطة برقم تعريف حساب "إحصاءات Google" المحدّد أو بمشروع Firebase المرتبط.

طلب الإصدار 1 من Admin API

GET https://analyticsadmin.googleapis.com/v1beta/properties?filter=parent:accounts/XXXXXX&key=[YOUR_API_KEY]

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

{
  "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"
    },
    ...
}

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

{
  "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"
      }
    },
    ...
}

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 في الإصدار 1 من Admin API معلومات عن موقع على "إحصاءات Google 4"، وهي تشبه طريقة webproperties.get في الإصدار 3 من Management API.

تجدر الإشارة إلى أنّ طريقة properties.get في Admin API تتوافق مع مواقع "إحصاءات Google 4" فقط.

طلب الإصدار 1 من Admin API

GET https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?key=[YOUR_API_KEY]

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

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

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

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

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 في الإصدار 1 من Admin API إلى إنشاء موقع جديد على "إحصاءات Google 4" يشبه طريقة webproperties.insert في الإصدار 3 من Management API.

طلب الإصدار 1 من Admin API

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

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

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

طلب الإصدار 3 من Management API

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

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

استجابة الإصدار 3 من Management API

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

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 في الإصدار 1 من Admin API على تعديل إعدادات موقع "إحصاءات Google 4"، وهي تشبه طريقة webproperties.patch في الإصدار 3 من Management API.

يُرجى ملاحظة المعلمة updateMask في عنوان URL للطلب، والتي تحتوي على قائمة الحقول المفصولة بفواصل التي سيتم تعديلها. لن يتم تعديل الحقول غير المتوفّرة في هذه القائمة. في حال استخدام مكتبة برامج، ستكون المَعلمة update_mask متاحة كجزء من توقيع الطريقة.

طلب الإصدار 1 من Admin API

PATCH https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?updateMask=displayName,industryCategory&key=[YOUR_API_KEY]

{
  "displayName": "New Property Name",
  "industryCategory": "FINANCE"
}

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

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

طلب الإصدار 3 من Management API

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

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

استجابة الإصدار 3 من Management API

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

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 حاليًا نموذج أذونات مستخدمين مشابهًا للإصدار 3 من Management API، ولكن مع بعض الاختلافات.

  1. يمكنك إدارة أذونات المستخدمين من خلال Google Analytics Admin API باستخدام موارد الحساب AccessBinding والموقع AccessBinding بدلاً من موارد AccountUserLink وWebPropertyUserLink وProfileUserLink في الإصدار الثالث من Management API.
  2. لا تتضمّن عمليات ربط الوصول إلى الموقع في واجهة برمجة التطبيقات Admin API في "إحصاءات Google" أذونات ضمنية أو أذونات مُكتسَبة من عمليات ربط الوصول إلى الحساب. في الإصدار 3 من Management API، تضمّن كل رابط مستخدِم مجموعة permissions.effective تضمّنت أذونات ضمنية ومكتسَبة.

يحتوي كيان AccessBinding على مستخدِم (عنوان بريد إلكتروني) وقائمة بالأدوار الممنوحة للمستخدم. يمكن إنشاء كيان AccessBinding أو تعديله أو حذفه.

في ما يلي عملية الربط بين أسماء الأدوار في الإصدار الأول من واجهة برمجة التطبيقات Admin API وأسماء أذونات الإصدار 3 من Management API:

دور الإصدار 1 من Admin API اسم إذن الإصدار 3 من Management API
الأدوار/المشاهد مسبقًا READ_AND_ANALYZE
الأدوار/المحلّل المحدَّدة مسبقًا التعاون
أدوار/محرّرين محدّدين مسبقًا تعديل
الأدوار/المشرف المحددة مسبقًا MANAGE_USERS

تم تقديم الأدوار predefinedRoles/no-cost-data وpredefinedRoles/no-revenue-data في الإصدار 1 من Admin API وليس لها أيّ عملية ربط مقابلة في Management API الإصدار 3.

يوضّح هذا الدليل كيفية إدارة عمليات ربط أذونات الوصول على مستوى الحساب. لإدارة عمليات ربط الوصول على مستوى الموقع، اتّبِع العملية نفسها، ولكن استخدِم موارد وأساليب الموقع AccessBinding بدلاً من الحساب AccessBinding.

إدراج عمليات ربط الوصول إلى الحساب

تعرض طريقة accounts.accessBindings.list في الإصدار 1 من Admin API جميع عمليات ربط الوصول في أحد الحسابات، تمامًا مثل طريقة accountUserLinks.list في الإصدار 3 من Management API.

طلب الإصدار 1 من Admin API

GET https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

{
  "accessBindings": [
    {
      "name": "accounts/XXXXXX/accessBindings/XXXXXX",
      "user": "XXXXXX",
      "roles": [
        "predefinedRoles/editor",
        "predefinedRoles/admin"
      ]
    }
  ]
}

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

{
  "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 في الإصدار 1 من Admin API على تعديل ربط الوصول إلى الحساب بطريقة تشبه طريقة accountUserLinks.update في الإصدار 3 من Management API.

طلب الإصدار 1 من Admin API

PATCH https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX

{
  "roles": [
    "predefinedRoles/editor",
    "predefinedRoles/admin"
  ]
}

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

{
  "name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
  "user": "USER-EMAIL",
  "directRoles": [
    "predefinedRoles/editor",
    "predefinedRoles/admin"
  ]
}

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

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

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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 في الإصدار 1 من Admin API ربط وصول في حساب يشبه طريقة accountUserLinks.insert في الإصدار 3 من Management API.

طلب الإصدار 1 من Admin API

POST https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings

{
  "roles": [
    "predefinedRoles/editor",
    "predefinedRoles/admin"
  ],
  "user": "USER-EMAIL"
}

استجابة الإصدار 1 من واجهة برمجة تطبيقات المشرف

{
  "name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
  "user": "USER-EMAIL",
  "roles": [
    "predefinedRoles/editor",
    "predefinedRoles/admin"
  ]
}

طلب الإصدار 3 من Management API

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

استجابة الإصدار 3 من Management API

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

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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

التجميع

لا يتيح الإصدار 1 من Admin API تجميع طلبات البيانات المتعددة من واجهة برمجة تطبيقات Google Analytics باستخدام نوع المحتوى المختلط/متعدد الأجزاء، بدلاً من Management API v3.

وبدلاً من ذلك، تتم إتاحة التجميع بشكل صريح على مستوى واجهة برمجة التطبيقات. تدعم الطرق التالية للإصدار 1 من Admin API وظائف التجميع:

رمز نموذجي لطلب الإصدار 1 من Admin API باستخدام مكتبات العملاء:

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

تغييرات حصص واجهة برمجة التطبيقات

يقدّم الإصدار الأول من Admin API حصصًا أقل تقييدًا مقارنةً بالإصدار الثالث من Management API.

  • يقتصر معدّل الطلبات الواردة إلى الإصدار 1 من Admin API على 600 طلب في الدقيقة تلقائيًا لمشروع Google Cloud Platform.
  • في الوقت الحالي، ما مِن حصة قصوى يومية على عدد طلبات البيانات من واجهة برمجة التطبيقات Admin API لكل مشروع على Google Cloud Platform. يُرجى العلم أنّ الحد الأقصى النظري لعدد الطلبات في اليوم لا يزال مقيَّدًا بحصة الطلبات في الدقيقة.
  • تمت إزالة الحد المنفصل لعدد عمليات الكتابة في اليوم.