البدء السريع لمطوّري Google Analytics Admin API

في هذا الدليل السريع، يمكنك إنشاء طلبات list وإرسالها إلى "واجهة برمجة تطبيقات المشرف في إحصاءات Google"، ثمّ الاطّلاع على الردود لإعداد إذن الوصول إلى واجهة برمجة التطبيقات والتحقّق منه.

يمكنك إكمال هذا الدليل السريع باستخدام حزمة SDK أو واجهة برمجة التطبيقات REST API في بيئتك المحلية أو مثيل VM على Google Cloud.

في ما يلي ملخّص للخطوات:

  • إعداد مشروع على Google Cloud وتفعيل Google Analytics Admin API
  • على جهازك المحلي أو مثيل جهاز افتراضي على السحابة الإلكترونية:
    • ثبِّت حزمة SDK وبدِّئ إعدادها وأكمِل عملية المصادقة باستخدام Google Cloud.
    • ثبِّت حزمة تطوير البرامج (SDK) للغة التي تريدها (اختياري).
  • ضبط المصادقة
  • ضبط أذونات الوصول إلى "إحصاءات Google"
  • إعداد حزمة تطوير برامج (SDK)
  • إجراء طلب بيانات من واجهة برمجة التطبيقات

إعداد مشروع على Google Cloud

انقر على الزرّ التالي تفعيل Google Analytics Admin API لاختيار مشروع جديد على Google Cloud أو إنشاؤه وتفعيل Google Analytics Admin API تلقائيًا.

تفعيل Google Analytics Admin API

إعداد Google Cloud

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

  1. ثبِّت Google Cloud وفعِّلها.

  2. للتأكّد من أنّ مكونات gcloud محدَّثة، شغِّل الأمر التالي.

    gcloud components update

لتجنُّب تقديم معرّف مشروعك إلى Google Cloud، يمكنك استخدام الأمر gcloud config set لضبط مشروع ومنطقة تلقائيَين.

ضبط المصادقة

يستخدم هذا الدليل السريع بيانات الاعتماد التلقائية للتطبيق للعثور تلقائيًا على بيانات الاعتماد استنادًا إلى بيئة التطبيق، حتى تتمكّن من عدم تغيير رمز العميل للمصادقة.

تتوافق Google Analytics Admin API مع حسابات المستخدمين و حسابات الخدمة:

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

لمزيد من المعلومات عن المصادقة وإعداد ملف اعتماد الحساب لتطبيقك، يُرجى الاطّلاع على مقالة طرق المصادقة في Google.

حساب المستخدمحساب الخدمة

أنشئ ملفًا محليًا لملف "بيانات اعتماد التطبيق التلقائية" (ADC) من خلال تنفيذ الأمر التالي. يُطلق هذا الأمر مسار ويب تقدّم فيه بيانات اعتماد المستخدم.

  gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

تذكَّر تحديد النطاقات المطلوبة من خلال Google Analytics Admin API في الأمر. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد "بيانات الاعتماد التلقائية للتطبيق".

في ما يلي خطوات المصادقة باستخدام حساب خدمة:

  1. أنشئ حساب خدمة.
  2. اربط حساب الخدمة بمثيل VM في Cloud من خلال تنفيذ الأمر التالي في gcloud CLI:
  gcloud compute instances stop YOUR-VM-INSTANCE-ID

  gcloud compute instances set-service-account YOUR-VM-INSTANCE-ID \
    --service-account YOUR-SERVICE-ACCOUNT-EMAIL-ALIAS  \
    --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

تذكَّر تحديد النطاقات المطلوبة من خلال Google Analytics Admin API في الأمر. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد "بيانات الاعتماد التلقائية للتطبيق".

ضبط أذونات الوصول إلى "إحصاءات Google"

منح "إحصاءات Google" إذن الوصول إلى عنوان البريد الإلكتروني المرتبط بحساب المستخدم أو حساب الخدمة

إعداد حزمة تطوير البرامج (SDK) للغة البرمجة

ثبِّت حزمة تطوير البرامج (SDK) الخاصة بلغة البرمجة على جهازك.

JavaPHPPythonNode.jsNET.RubyانتقالREST

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

دليل تثبيت مكتبة برامج لواجهة برمجة التطبيقات PHP

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

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

دليل تثبيت مكتبة عملاء ‎.NET

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

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

يمكنك ضبط متغيّرات البيئة عن طريق إدخال ما يلي: استبدِل PROJECT_ID بمعرّف مشروعك على Google Cloud. 

  EXPORT PROJECT_ID=PROJECT_ID

تقديم طلب بيانات من واجهة برمجة التطبيقات

شغِّل الرمز البرمجي التالي لإجراء مكالمتك الأولى:

JavaPHPPythonNode.jsNET.REST

google-analytics-admin/src/main/java/com/google/analytics/admin/samples/QuickstartSample.java
الفتح في Cloud Shell العرض على GitHub 
import com.google.analytics.admin.v1beta.Account;
import com.google.analytics.admin.v1beta.AnalyticsAdminServiceClient;
import com.google.analytics.admin.v1beta.AnalyticsAdminServiceClient.ListAccountsPage;
import com.google.analytics.admin.v1beta.AnalyticsAdminServiceClient.ListAccountsPagedResponse;
import com.google.analytics.admin.v1beta.ListAccountsRequest;

/**
 * This application demonstrates the usage of the Analytics Admin API using service account
 * credentials. For more information on service accounts, see
 * https://cloud.google.com/iam/docs/understanding-service-accounts.
 *
 * <p>The following document provides instructions on setting service account credentials for your
 * application: https://cloud.google.com/docs/authentication/production
 *
 * <p>In a nutshell, you need to:
 *
 * <ol>
 *   <li>Create a service account and download the key JSON file as described at
 *       https://cloud.google.com/docs/authentication/production#creating_a_service_account.
 *   <li>Provide service account credentials using one of the following options:
 *       <ul>
 *         <li>Set the {@code GOOGLE_APPLICATION_CREDENTIALS} environment variable. The API client
 *             will use the value of this variable to find the service account key JSON file. See
 *             https://cloud.google.com/docs/authentication/production#setting_the_environment_variable
 *             for more information.
 *             <p>OR
 *         <li>Manually pass the path to the service account key JSON file to the API client by
 *             specifying the {@code keyFilename} parameter in the constructor. See
 *             https://cloud.google.com/docs/authentication/production#passing_the_path_to_the_service_account_key_in_code
 *             for more information.
 *       </ul>
 * </ol>
 *
 * <p>To run this sample using Maven:
 *
 * <pre>{@code
 * cd google-analytics-data
 * mvn compile exec:java -Dexec.mainClass="com.google.analytics.admin.samples.QuickstartSample"
 * }</pre>
 */
public class QuickstartSample {

  public static void main(String... args) throws Exception {
    listAccounts();
  }

  // This is an example snippet that calls the Google Analytics Admin API and lists all Google
  // Analytics accounts available to the authenticated user.
  static void listAccounts() throws Exception {
    // Instantiates a client using default credentials.
    // See https://cloud.google.com/docs/authentication/production for more information
    // about managing credentials.
    try (AnalyticsAdminServiceClient analyticsAdmin = AnalyticsAdminServiceClient.create()) {
      // Calls listAccounts() method of the Google Analytics Admin API and prints
      // the response for each account.
      ListAccountsPagedResponse response =
          analyticsAdmin.listAccounts(ListAccountsRequest.newBuilder().build());
      for (ListAccountsPage page : response.iteratePages()) {
        for (Account account : page.iterateAll()) {
          System.out.printf("Account name: %s%n", account.getName());
          System.out.printf("Display name: %s%n", account.getDisplayName());
          System.out.printf("Country code: %s%n", account.getRegionCode());
          System.out.printf("Create time: %s%n", account.getCreateTime().getSeconds());
          System.out.printf("Update time: %s%n", account.getUpdateTime().getSeconds());
          System.out.println();
        }
      }
    }
  }
}

QuickstartSample.java

google-analytics-admin/quickstart.php
الفتح في Cloud Shell العرض على GitHub 
require 'vendor/autoload.php';

use Google\Analytics\Admin\V1beta\Account;
use Google\Analytics\Admin\V1beta\Client\AnalyticsAdminServiceClient;
use Google\Analytics\Admin\V1beta\ListAccountsRequest;

/**
 * TODO(developer): Replace this variable with your Google Analytics 4
 *   property ID before running the sample.
 */
$property_id = 'YOUR-GA4-PROPERTY-ID';

// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
// See https://cloud.google.com/docs/authentication/production for more information
// about managing credentials.
$client = new AnalyticsAdminServiceClient();

// Calls listAccounts() method of the Google Analytics Admin API and prints
// the response for each account.
$request = new ListAccountsRequest();
$response = $client->listAccounts($request);

print 'Result:' . PHP_EOL;
foreach ($response->iterateAllElements() as $account) {
    print 'Account name: ' . $account->getName() . PHP_EOL;
    print 'Display name: ' . $account->getDisplayName() . PHP_EOL;
    print 'Country code: ' . $account->getRegionCode() . PHP_EOL;
    print 'Create time: ' . $account->getCreateTime()->getSeconds() . PHP_EOL;
    print 'Update time: ' . $account->getUpdateTime()->getSeconds() . PHP_EOL;
}
quickstart.php

google-analytics-admin/quickstart.py
الفتح في Cloud Shell العرض على GitHub 
def list_accounts(transport: str = None):
    """
    Lists the available Google Analytics accounts.

    Args:
        transport(str): The transport to use. For example, "grpc"
            or "rest". If set to None, a transport is chosen automatically.
    """
    from google.analytics.admin import AnalyticsAdminServiceClient

    # Using a default constructor instructs the client to use the credentials
    # specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = AnalyticsAdminServiceClient(transport=transport)

    results = client.list_accounts()

    # Displays the configuration information for all Google Analytics accounts
    # available to the authenticated user.
    print("Result:")
    for account in results:
        print(account)


quickstart.py

google-analytics-admin/quickstart.js
الفتح في Cloud Shell العرض على GitHub 
  // Imports the Google Analytics Admin API client library.
  const analyticsAdmin = 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 analyticsAdmin.AnalyticsAdminServiceClient();

  // Lists all Google Analytics accounts available to the authenticated user.
  async function listAccounts() {
    // Uses listAccounts() with no arguments to fetch all pages. For more
    // information on pagination in the Node.js library, see:
    // https://github.com/googleapis/gax-nodejs/blob/main/client-libraries.md#auto-pagination
    const [response] = await analyticsAdminClient.listAccounts();

    console.log('Accounts:');
    for (const account of response) {
      console.log('Account name:', account.name);
      console.log('Display name:', account.displayName);
      console.log('Region code:', account.regionCode);
      console.log('Create time:', account.createTime.seconds);
      console.log('Update time:', account.updateTime.seconds);
    }
  }

  listAccounts();
quickstart.js

analytics-admin/QuickStart/QuickStart.cs
الفتح في Cloud Shell العرض على GitHub 
using Google.Analytics.Admin.V1Beta;
using Google.Api.Gax;
using System;

namespace AnalyticsSamples
{
    class QuickStart
    {
        static void Main(string[] args)
        {
            AnalyticsAdminServiceClient client = AnalyticsAdminServiceClient.Create();
            PagedEnumerable<ListAccountsResponse, Account> response =
                client.ListAccounts( new ListAccountsRequest() );
            foreach( Account account in response )
            {
                Console.WriteLine("Account name: {0}", account.Name);
                Console.WriteLine("Display name: {0}", account.DisplayName);
                Console.WriteLine("Region code: {0}", account.RegionCode);
                Console.WriteLine("Update time: {0}", account.UpdateTime);
                Console.WriteLine("Create time: {0}", account.CreateTime);
                Console.WriteLine();
            }
        }
    }
}
QuickStart.cs

لإرسال هذا الطلب، يمكنك تنفيذ الأمر curl من سطر الأوامر أو تضمين طلب REST في تطبيقك. 

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  https://analyticsadmin.googleapis.com/v1beta/accounts

يسرد نموذج استجابة الرمز البرمجي حسابات "إحصاءات Google" التي يمكن للمستخدم أو حساب الخدمة الاطّلاع عليها:

{
  "accounts": [
    {
      "name": "accounts/123456789",
      "createTime": "2025-01-01T00:12:23.456Z",
      "createTime": "2025-01-01T00:12:23.456Z",
      "displayName": "Demo Account",
      "regionCode": "US",
      "gmpOrganization": "marketingplatformadmin.googleapis.com/organizations/abcdef12345678"
    }
}