מדריך למפתחים בנושא Google Analytics Admin API

במדריך למתחילים הזה תלמדו ליצור ולשלוח בקשות list ל-Google Analytics Admin API, ואז להציג את התשובות כדי להגדיר ולאמת את הגישה ל-API.

אפשר להשלים את המדריך למתחילים הזה באמצעות SDK, או באמצעות ה-API ל-REST בסביבה המקומית או במכונה וירטואלית ב-Google Cloud.

זהו סיכום השלבים:

• מגדירים פרויקט ב-Google Cloud ומפעילים את Google Analytics Admin API.
• במכונה המקומית או במכונה הווירטואלית ב-Cloud:
  • התקנה, הפעלה ואימות באמצעות Google Cloud.
  • מתקינים את ה-SDK בשפה הרצויה (אופציונלי).
• מגדירים את האימות.
• מגדירים את הגישה ל-Google Analytics.
• מגדירים SDK.
• מריצים קריאה ל-API.

הגדרת פרויקט ב-Google Cloud

לוחצים על הלחצן Enable the 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 כדי להגדיר פרויקט ואזור ברירת מחדל.

הגדרת אימות

במדריך למתחילים הזה נעשה שימוש ב-Application Default Credentials כדי למצוא באופן אוטומטי את פרטי הכניסה על סמך הסביבה שבה פועלת האפליקציה, כך שלא תצטרכו לשנות את קוד הלקוח כדי לבצע אימות.

Google Analytics Admin API תומך בחשבונות משתמשים ובחשבונות שירות:

• חשבונות משתמשים מייצגים מְפַתֵּחַ, אדמין או כל אדם אחר שמנהל אינטראקציה עם ממשקי ה-API והשירותים של Google.
• חשבונות שירות לא מייצגים משתמש אנושי ספציפי. הם מספקים דרך לנהל את האימות וההרשאות בלי מעורבות ישירה של בני אדם, למשל כדי לתת לאפליקציות גישה למשאבים של Google Cloud.

למידע נוסף על אימות ועל הגדרת פרטי כניסה לחשבון באפליקציה, קראו את המאמר שיטות אימות ב-Google.

חשבון משתמשחשבון שירות

מריצים את הפקודה הבאה כדי ליצור קובץ מקומי של Application Default Credentials‏ (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 בפקודה. מידע נוסף זמין במאמר הגדרה של Application Default Credentials.

אלה השלבים לביצוע אימות באמצעות חשבון שירות:

1. יוצרים חשבון שירות.
2. מקשרים את חשבון השירות למכונה הווירטואלית ב-Cloud באמצעות הפקודה הבאה ב-CLI של gcloud:

  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 בפקודה. מידע נוסף זמין במאמר הגדרה של Application Default Credentials.

הגדרת הגישה ל-Google Analytics

נותנים ל-Google Analytics גישה לכתובת האימייל שמשויכת לחשבון המשתמש או לחשבון השירות שלכם.

הגדרת ה-SDK לשפת התכנות שלכם

מתקינים את ה-SDK של שפת התכנות במחשב המקומי.

JavaPHPPythonNode.js‎.NETRubyGoREST

מדריך להתקנת ספריית לקוח 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

ביצוע קריאה ל-API

מריצים את הקוד הבא כדי לבצע את הקריאה הראשונה:

JavaPHPPythonNode.js‎.NETREST

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 Analytics שלמשתמש או לחשבון השירות יש גישה לצפות בהם:

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