Zur Google Analytics Admin API Version 1 migrieren

Die Alpha- und Betakanäle der API werden weiterhin unterstützt. Die Betaversion enthält einen Teil der in der Alphaversion verfügbaren Funktionen, die als stabil gelten und in Zukunft voraussichtlich keine wesentlichen Änderungen unterliegen. Neue Funktionen werden der Betaversion hinzugefügt, sobald sie ausgereift sind.

In diesem Dokument wird beschrieben, wie Sie vorhandenen Code von der Google Analytics Management API (Version 3) zur Google Analytics Admin API (Version 1) migrieren. Außerdem erhalten Sie einen kurzen Überblick über die wichtigsten Unterschiede zwischen den beiden APIs.

Warum muss ich migrieren?

Wenn in Ihrer Anwendung eine Google Analytics 4-Property erstellt oder konfiguriert werden muss, muss die Admin API Version 1 verwendet werden. Die Management API Version 3 funktioniert nur mit Universal Analytics-Properties und die Admin API Version 1 nur mit Google Analytics 4-Properties.

Voraussetzungen

Machen Sie sich in der Kurzanleitung mit den Grundlagen der Admin API Version 1 vertraut.

Erste Schritte

Zuerst bereiten Sie eine Google Analytics 4-Property vor, aktivieren Version 1 der Admin API und richten dann eine geeignete API-Clientbibliothek für Ihre Plattform ein.

Google Analytics 4-Property vorbereiten

Bevor Sie Ihren Code zur Unterstützung der Admin API v1 migrieren, müssen Sie Ihre Website für eine Google Analytics 4-Property migrieren.

API aktivieren

Klicken Sie auf diese Schaltfläche, um die Admin API v1 im ausgewählten Google Cloud-Projekt automatisch zu aktivieren.

Google Analytics Admin API aktivieren

Clientbibliothek verwenden

Clientbibliothek installieren

Wenn Sie eine Clientbibliothek verwenden, müssen Sie die Admin API v1-Clientbibliothek für Ihre Programmiersprache installieren.

Clientbibliothek initialisieren

Die Admin API v1-Clientbibliotheken wurden für einen schnellen Einstieg entwickelt. Standardmäßig versuchen Clientbibliotheken, die Anmeldedaten Ihres Dienstkontos automatisch zu finden.

Eine einfache Möglichkeit zur Bereitstellung von Dienstkonto-Anmeldedaten ist, die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festzulegen. Der API-Client verwendet den Wert dieser Variablen, um die JSON-Datei mit dem Dienstkontoschlüssel zu finden.

Sie können beispielsweise die Anmeldedaten für ein Dienstkonto festlegen, indem Sie den folgenden Befehl ausführen und den Pfad zur JSON-Datei des Dienstkontos verwenden:

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

Unten finden Sie die Code-Snippets, die häufig zum Initialisieren der Admin API v1-Clientbibliotheken verwendet werden.

Java

    try (AnalyticsAdminServiceClient analyticsAdmin = AnalyticsAdminServiceClient.create()) {

Python

client = BetaAnalyticsAdminClient()

.NET

BetaAnalyticsAdminClient client = BetaAnalyticsAdminClient.Create();

PHP

$client = new AlphaAnalyticsAdminClient();

Node.js

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

Anstatt eine Umgebungsvariable zu verwenden, ist es auch möglich, die Anmeldedaten während der Initialisierung explizit an eine API-Clientinstanz weiterzugeben.

Wenn Sie keine Clientbibliothek verwenden

Wenn Sie die Management API Version 3 ohne Clientbibliothek verwenden, aber mit der Admin API Version 1 fortfahren möchten, können Sie weiterhin Ihre Anmeldedaten verwenden.

Sie müssen den neuen HTTP-Endpunkt und das Discovery-Dokument verwenden, die von der Admin API bereitgestellt werden:

Wenn Ihr Code ein Discovery-Dokument nutzt, müssen Sie es auf das von der Admin API Version 1 bereitgestellte Discovery-Dokument aktualisieren:

Nachdem Sie den Endpunkt aktualisiert haben, müssen Sie sich mit der neuen Anfragestruktur und den Konzepten der Admin API vertraut machen, damit Sie Ihre JSON-Abfrage aktualisieren können.

Häufige Aufgaben

Konten verwalten

Version 1 der Admin API bietet eine Reihe von Google Analytics-Methoden zur Konto- und Property-Verwaltung, die mit Version 3 der Management API vergleichbar sind. Außerdem bietet die Admin API Version 1 Funktionen zum Bereitstellen, Löschen und Aktualisieren von Google Analytics-Konten.

  • Von den Verwaltungsmethoden für Properties der Admin API Version 1 werden nur Google Analytics 4-Properties unterstützt.

  • Das Konzept der Datenansichten (Profile) ist in der Admin API Version 1 nicht vorhanden.

  • Seit der Einführung von Datenstreams in Google Analytics 4 sind bestimmte Informationen auf Property-Ebene nicht mehr vorhanden. Beispielsweise ist das Feld websiteUrl jetzt in der Entität DataStream und nicht Teil des Property-Objekts vorhanden.

Kontozusammenfassungen auflisten

Die Methode accountSummaries der Admin API gibt einfache Zusammenfassungen aller Konten zurück, auf die der Aufrufer zugreifen kann, ähnlich wie die Methode accountSummaries der Management API Version 3.

Ein wichtiger Unterschied besteht darin, dass die Admin API Version 1 nur Informationen zu Google Analytics 4-Properties zurückgibt, während die Antworten der Management API Version 3 Daten zu Properties enthalten, die mit Universal Analytics erstellt wurden. Es ist nicht möglich, Informationen zu beiden Attributtypen mit einem einzigen Aufruf abzurufen.

Da es in Google Analytics 4 keine Datenansichten (Profile) gibt, enthalten die von der Admin API zurückgegebenen Kontozusammenfassungen keine Informationen zu Datenansichten (Profilen).

Die Google Analytics 4-Kontoübersichtsdaten sind auf die Ressourcen- und Anzeigenamen der Konten/Properties beschränkt, die für den aktuellen Nutzer verfügbar sind.

Verwenden Sie die Ressourcennamen, die in den Feldern account und property der Zusammenfassungsantwort zurückgegeben werden, um die vollständigen Konfigurationsdaten durch Aufrufen der Methoden account.get und property.get abzurufen.

Admin API Version 1-Anfrage

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

Antwort der Admin API v1

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

Anfrage an die Management API Version 3

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

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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


Konten auflisten

Mit der Methode accounts.list der Admin API Version 1 werden alle Konten zurückgegeben, auf die mit dem Aufrufer zugegriffen werden kann. Dies ähnelt der Methode accounts.list der Management API Version 3.

Admin API Version 1-Anfrage

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

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

Anfrage an die Management API Version 3

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

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

Die Antwort der Admin API Version 1 enthält weder Informationen zu gültigen Nutzerberechtigungen noch das Feld childLink, das in der Management API Version 3 vorhanden war.

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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)


Properties verwalten

Listenattribute

Mit der Methode properties.list der Admin API Version 1 werden alle Google Analytics 4-Properties zurückgegeben, auf die der Aufrufer zugreifen kann. Dies ähnelt der Methode webproperties.list der Management API Version 3, mit der alle verfügbaren Universal Analytics-Properties zurückgegeben werden.

Da das Feld websiteUrl in Google Analytics 4 auf Property-Ebene nicht mehr vorhanden ist, verwenden Sie properties.dataStreams/list, um alle mit der Property verknüpften Datenstreams aufzulisten, und suchen Sie im Feld defaultUri nach der Website-URL, die einem Stream zugeordnet ist.

Beachten Sie den Parameter filter in der URL der properties.list-Anfrage. Der Wert des Parameters enthält einen Ausdruck zum Filtern der Ergebnisse der Anfrage. Er kann verwendet werden, um die Properties aufzulisten, die der angegebenen Google Analytics-Konto-ID oder dem verknüpften Firebase-Projekt zugeordnet sind.

Admin API Version 1-Anfrage

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

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

Anfrage an die Management API Version 3

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

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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


Attribut abrufen

Mit der Methode properties.get der Admin API Version 1 werden Informationen zu einer Google Analytics 4-Property zurückgegeben, ähnlich der Methode webproperties.get der Management API Version 3.

Die Methode properties.get der Admin API unterstützt nur Google Analytics 4-Properties.

Admin API Version 1-Anfrage

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

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

Anfrage an die Management API Version 3

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

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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


Property erstellen

Mit der Methode properties.create der Admin API Version 1 wird eine neue Google Analytics 4-Property erstellt, ähnlich der Methode webproperties.insert der Management API Version 3.

Admin API Version 1-Anfrage

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

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

Anfrage an die Management API Version 3

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

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

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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_)


Attribut aktualisieren/patchen

Mit der Methode properties.patch der Admin API Version 1 wird die Konfiguration einer Google Analytics 4-Property aktualisiert, ähnlich der Methode webproperties.patch der Management API Version 3.

Achten Sie auf den updateMask-Parameter in der URL der Anfrage, der die durch Kommas getrennte Liste der zu aktualisierenden Felder enthält. Felder, die in dieser Liste nicht vorhanden sind, werden nicht aktualisiert. Wenn Sie eine Clientbibliothek verwenden, ist der Parameter update_mask als Teil der Methodensignatur verfügbar.

Admin API Version 1-Anfrage

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

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

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

Anfrage an die Management API Version 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"
}

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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_)


Nutzer verwalten

Die Google Analytics Admin API implementiert derzeit ein Nutzerberechtigungsmodell, das der Management API Version 3 ähnelt. Es gibt jedoch einige Unterschiede.

  1. Nutzerberechtigungen werden mit der Google Analytics Admin API über die Ressourcen Konto AccessBinding und Property AccessBinding anstelle der Ressourcen AccountUserLink, WebPropertyUserLink und ProfileUserLink der Management API Version 3 verwaltet.
  2. Property-Zugriffsbindungen in der Google Analytics Admin API enthalten keine implizierten Berechtigungen oder Berechtigungen, die von Kontozugriffsbindungen übernommen werden. In der Management API Version 3 enthielt jeder Nutzerlink eine permissions.effective-Sammlung mit impliziten und übernommenen Berechtigungen.

Eine AccessBinding-Entität enthält einen Nutzer (E-Mail-Adresse) und eine Liste der Rollen, die dem Nutzer zugewiesen sind. Eine AccessBinding-Entität kann erstellt, aktualisiert oder gelöscht werden.

Die Zuordnung zwischen den Rollennamen der Admin API Version 1 und den Berechtigungsnamen der Management API Version 3 sieht so aus:

Admin API V1-Rolle Name der Berechtigung für die Management API Version 3
vordefinierte Rollen/Betrachter READ_AND_ANALYZE
vordefinierte Rollen/Analysten ZUSAMMENARBEITEN
vordefinierter rollen/editor BEARBEITEN
vordefinierte Rollen/Admin MANAGE_USERS

Die Rollen predefinedRoles/no-cost-data und predefinedRoles/no-revenue-data wurden in der Admin API Version 1 eingeführt und haben in der Management API Version 3 keine entsprechende Zuordnung.

In diesem Leitfaden wird gezeigt, wie Sie Zugriffsbindungen auf Kontoebene verwalten. Zum Verwalten von Zugriffsbindungen auf Property-Ebene gehen Sie genauso vor, verwenden jedoch Property-AccessBinding-Ressourcen und -Methoden anstelle des Kontos AccessBinding.

Kontozugriffsbindungen auflisten

Mit der Methode accounts.accessBindings.list der Admin API Version 1 werden alle Zugriffsbindungen für ein Konto aufgelistet, ähnlich der Methode accountUserLinks.list der Management API Version 3.

Admin API Version 1-Anfrage

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

Antwort der Admin API v1

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

Anfrage an die Management API Version 3

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

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

Beispielcode zum Aufrufen der Admin API mit Clientbibliotheken:

Python

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


Kontoverknüpfungen aktualisieren

Mit der Methode accounts.accessBindings.patch der Admin API Version 1 wird eine Zugriffsbindung eines Kontos aktualisiert, ähnlich wie bei der Methode accountUserLinks.update der Management API Version 3.

Admin API Version 1-Anfrage

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

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

Antwort der Admin API v1

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

Anfrage an die Management API Version 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"
    ]
  }
}

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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)


Kontoverknüpfungen erstellen

Mit der Methode accounts.accessBindings.create der Admin API Version 1 wird eine Zugriffsbindung in einem Konto erstellt, ähnlich der Methode accountUserLinks.insert der Management API Version 3.

Admin API Version 1-Anfrage

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

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

Antwort der Admin API v1

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

Anfrage an die Management API Version 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"
    ]
  }
}

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

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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)


Batching

Im Gegensatz zur Management API v3 unterstützt die Admin API v1 die Batchverarbeitung mehrerer Google Analytics API-Aufrufe mit dem Inhaltstyp "mehrteiliger/gemischter Inhalte" nicht.

Stattdessen wird die Batchverarbeitung explizit auf API-Ebene unterstützt. Die folgenden Methoden der Admin API Version 1 unterstützen die Batchfunktion:

Beispielcode zum Aufrufen der Admin API Version 1 mit Clientbibliotheken:

Python

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


Änderungen des API-Kontingents

Mit der Admin API Version 1 gelten im Vergleich zur Management API Version 3 weniger restriktive Kontingente.

  • Die Anzahl der Anfragen an die Admin API v1 ist für ein GCP-Projekt standardmäßig auf 600 Anfragen pro Minute begrenzt.
  • Derzeit gibt es kein Tageslimit für die Anzahl der Aufrufe der Admin API v1 pro GCP-Projekt. Beachten Sie, dass die theoretische maximale Anzahl von Anfragen pro Tag weiterhin durch das Kontingent Anfragen pro Minute begrenzt ist.
  • Ein separates Limit für die Anzahl der Schreibvorgänge pro Tag wurde aufgehoben.