Google Analytics Admin API v1로 이전

이 문서에서는 기존 코드를 Google Analytics Management API v3에서 Google Analytics Admin API v1로 이전하는 방법을 안내하고 두 API 간 주요 차이점을 간략히 설명합니다.

현재 Admin API v1은 알파 버전이며, 변경될 수 있습니다.

이전을 해야 하는 이유는 무엇인가요?

애플리케이션에서 Google 애널리틱스 4 속성을 만들거나 구성해야 하는 경우 Admin API v1을 사용해야 합니다. Management API v3는 유니버설 애널리틱스 속성에서만 작동하며 Admin API v1은 Google 애널리틱스 4 속성에서만 작동합니다.

기본 요건

빠른 시작 가이드를 참고하여 Admin API v1의 기본 사항을 숙지하는 것이 좋습니다.

시작하기

시작하려면 Google 애널리틱스 4 속성을 준비하고 Admin API v1을 사용 설정한 다음, 플랫폼에 적합한 API 클라이언트 라이브러리를 설정합니다.

Google 애널리틱스 4 속성 준비

Admin API v1을 지원하도록 코드를 이전하기 전에 Google 애널리틱스 4 속성을 사용할 수 있도록 웹사이트를 이전해야 합니다.

API 사용 설정

선택한 Google Cloud 프로젝트에서 Admin API v1을 자동으로 사용 설정하려면 이 버튼을 클릭합니다.

Google Analytics Admin API 사용 설정

클라이언트 라이브러리 사용

클라이언트 라이브러리 설치

클라이언트 라이브러리를 사용하는 경우, 프로그래밍 언어에 사용할 Admin API v1 클라이언트 라이브러리를 설치해야 합니다.

클라이언트 라이브러리 초기화

Admin API v1 클라이언트 라이브러리는 개발자가 빠르게 시작할 수 있도록 설계되었습니다. 기본적으로 클라이언트 라이브러리는 서비스 계정 사용자 인증 정보를 자동으로 찾으려고 시도합니다.

GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하면 서비스 계정 사용자 인증 정보를 쉽게 제공할 수 있으며, API 클라이언트가 이 변수의 값을 사용하여 서비스 계정 키 JSON 파일을 찾습니다.

예를 들어 다음 명령어를 실행하고 서비스 계정 JSON 파일 경로를 사용하여 서비스 계정 사용자 인증 정보를 설정할 수 있습니다.

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

다음은 Admin API v1 클라이언트 라이브러리를 초기화하는 데 일반적으로 사용되는 코드 스니펫입니다.

자바

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

Python

client = AlphaAnalyticsAdminClient()

.NET

AlphaAnalyticsAdminClient client = AlphaAnalyticsAdminClient.Create();

PHP

$client = new AlphaAnalyticsAdminClient();

Node.js

  // Imports the Google Analytics Data API client library.
  const {AlphaAnalyticsAdminClient} = require('@google-analytics/admin');

  // Using a default constructor instructs the client to use the credentials
  // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
  const analyticsAdminClient = new AlphaAnalyticsAdminClient();

환경 변수를 사용하는 대신, 초기화 과정에서 사용자 인증 정보 정보를 API 클라이언트 인스턴스에 명시적으로 전달할 수 있습니다.

클라이언트 라이브러리를 사용하지 않는 경우

클라이언트 라이브러리 없이 Management API v3를 사용하고 Admin API v1에서도 계속 클라이언트 라이브러리를 사용하지 않으려면, 사용자 인증 정보를 그대로 사용하면 됩니다.

Admin API에서 제공하는 새 HTTP 엔드포인트 및 검색 문서를 사용해야 합니다.

코드가 검색 문서를 활용하는 경우, Admin API v1에서 제공하는 검색 문서로 업데이트해야 합니다.

엔드포인트를 업데이트한 후, JSON 쿼리를 업데이트하려면 Admin API의 새로운 요청 구조와 개념을 숙지해야 합니다.

일반적인 작업

계정 관리

Admin API v1은 Management API v3와 비슷한 일련의 Google 애널리틱스 계정 및 속성 관리 메서드를 제공합니다. 또한 Admin API v1에는 Google 애널리틱스 계정을 프로비저닝, 삭제, 업데이트하는 기능이 도입되었습니다.

  • Admin API v1 속성 관리 메서드는 Google 애널리틱스 4 속성만 지원합니다.

  • Admin API v1에는 보기(프로필) 개념이 없습니다.

  • Google 애널리틱스 4에 데이터 스트림이 도입되었으므로, 특정 정보는 더 이상 속성 수준에서 존재하지 않습니다. 예를 들어 이제 websiteUrl 필드는 속성 개체의 일부가 아니라 WebDataStream 항목에 표시됩니다.

계정 요약 나열

Admin API의 accountSummaries 메서드Management API v3의 accountSummaries 메서드와 마찬가지로, 호출자가 액세스할 수 있는 모든 계정의 간단한 요약을 반환합니다.

중요한 차이점은 Admin API v1은 Google 애널리틱스 4 속성에 관한 정보만 반환하지만, Management API v3 응답은 유니버설 애널리틱스로 생성된 속성에 대한 데이터를 포함한다는 점입니다. 단일 호출을 사용하여 두 가지 유형의 속성에 대한 정보를 모두 검색할 수는 없습니다.

Google 애널리틱스 4에는 보기(프로필)가 없으므로 Admin API에서 반환하는 계정 요약에는 보기(프로필) 정보가 포함되지 않습니다.

Google 애널리틱스 4 계정 요약 데이터는 현재 사용자가 사용할 수 있는 계정/속성의 리소스 및 표시 이름으로 제한됩니다.

account.getproperty.get 메서드를 호출하여 전체 구성 데이터를 검색할 수 있도록 요약 응답의 account, property 필드에서 반환된 리소스 이름을 사용합니다.

Admin API v1 요청

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

Admin API v1 응답

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

Management API v3 요청

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

Management API v3 응답

{
  "kind": "analytics#accountSummaries",
  "username": "XXXXXX",
  "totalResults": 9,
  "startIndex": 1,
  "itemsPerPage": 1000,
  "items": [
    {
      "id": "XXXXXX",
      "kind": "analytics#accountSummary",
      "name": "Test Account",
      "webProperties": [
        {
          "kind": "analytics#webPropertySummary",
          "id": "UA-XXXXXX",
          "name": "Test Property",
          "internalWebPropertyId": "XXXXXX",
          "level": "STANDARD",
          "websiteUrl": "XXXXXX",
          "profiles": [
            {
              "kind": "analytics#profileSummary",
              "id": "XXXXXX",
              "name": "Test Profile",
              "type": "WEB"
            }
          ]
        },
        ...
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

from google.analytics.admin import AnalyticsAdminServiceClient

def list_account_summaries():
    """Returns summaries of all accounts accessible by the caller."""
    client = AnalyticsAdminServiceClient()
    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()


계정 나열

Admin API v1의 accounts.list 메서드Management API v3의 accounts.list 메서드와 마찬가지로, 호출자가 액세스할 수 있는 모든 계정을 반환합니다.

Admin API v1 요청

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

Admin API v1 응답

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

Management API v3 요청

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

Management API v3 응답

{
  "kind": "analytics#accounts",
  "username": "XXXXXX",
  "totalResults": 9,
  "startIndex": 1,
  "itemsPerPage": 1000,
  "items": [
    {
      "id": "XXXXXX",
      "kind": "analytics#account",
      "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
      "name": "Test Account",
      "permissions": {
        "effective": [
          "COLLABORATE",
          "EDIT",
          "READ_AND_ANALYZE"
        ]
      },
      "created": "2020-02-21T00:17:33.282Z",
      "updated": "2021-01-07T02:47:57.386Z",
      "childLink": {
        "type": "analytics#webproperties",
        "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties"
      }
    },
    ...
}

Admin API v1 응답에는 효과적인 사용자 권한도 Management API v3에 있던 childLink 필드에 대한 정보도 포함되지 않습니다.

응답에는 현재 Google 애널리틱스 4 속성이 없을지도 모르는 계정도 포함됩니다.

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

from google.analytics.admin import AnalyticsAdminServiceClient

from accounts_get import print_account

def list_accounts():
    """Lists the Google Analytics accounts available to the current user."""
    client = AnalyticsAdminServiceClient()
    results = client.list_accounts()

    print("Result:")
    for account in results:
        print_account(account)


속성 관리

속성 나열

Admin API v1의 properties.list 메서드는 액세스 가능한 모든 유니버설 애널리틱스 속성을 반환하는 Management API v3의 webproperties.list 메서드와 마찬가지로, 호출자가 액세스할 수 있는 모든 Google 애널리틱스 4 속성을 반환합니다.

websiteUrl 필드는 Google 애널리틱스 4의 속성 수준에 더 이상 존재하지 않으므로 properties.webDataStreams/list를 사용하여 속성과 관련된 웹 데이터 스트림을 모두 나열하고 defaultUri 필드를 조회하여 스트림과 연결된 웹사이트 URL을 검색합니다.

properties.list 요청의 URL에서 filter 매개변수를 확인합니다. 해당 매개변수의 값은 요청 결과를 필터링하는 표현식을 포함하며, 지정된 Google 애널리틱스 계정 ID 또는 연결된 Firebase 프로젝트와 연결된 속성을 나열하는 데 사용할 수 있습니다.

Admin API v1 요청

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

Admin API v1 응답

{
  "properties": [
    {
      "name": "properties/XXXXXX",
      "parent": "accounts/XXXXXX",
      "createTime": "2020-10-29T04:02:49.124Z",
      "updateTime": "2020-10-29T04:02:49.124Z",
      "displayName": "Test Property",
      "timeZone": "America/Los_Angeles",
      "currencyCode": "USD"
    },
    ...
}

Management API v3 요청

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

Management API v3 응답

{
  "kind": "analytics#webproperties",
  "username": "XXXXXX",
  "totalResults": 33,
  "startIndex": 1,
  "itemsPerPage": 1000,
  "items": [
    {
      "id": "UA-XXXXXX-1",
      "kind": "analytics#webproperty",
      "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1",
      "accountId": "XXXXXX",
      "internalWebPropertyId": "XXXXXX",
      "name": "Test Account",
      "websiteUrl": "XXXXXX",
      "level": "PREMIUM",
      "profileCount": 4,
      "industryVertical": "HEALTH",
      "defaultProfileId": "XXXXXX",
      "dataRetentionTtl": "INDEFINITE",
      "dataRetentionResetOnNewActivity": true,
      "permissions": {
        "effective": [
          "COLLABORATE",
          "EDIT",
          "READ_AND_ANALYZE"
        ]
      },
      "created": "2020-02-21T00:28:47.287Z",
      "updated": "2021-01-27T21:39:22.704Z",
      "parentLink": {
        "type": "analytics#account",
        "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
      },
      "childLink": {
        "type": "analytics#profiles",
        "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/profiles"
      }
    },
    ...
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

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):
    """Lists Google Analytics 4 properties under the specified parent account
    that are available to the current user."""
    client = AnalyticsAdminServiceClient()
    results = client.list_properties(
        ListPropertiesRequest(filter=f"parent:accounts/{account_id}", show_deleted=True)
    )

    print("Result:")
    for property_ in results:
        print(property_)
        print()


속성 가져오기

Admin API v1의 properties.get 메서드Management API v3의 webproperties.get 메서드와 마찬가지로, Google 애널리틱스 4 속성에 대한 정보를 반환합니다.

Admin API의 properties.get 메서드는 Google 애널리틱스 4 속성만 지원합니다.

Admin API v1 요청

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

Admin API v1 응답

{
  "name": "properties/XXXXXX",
  "parent": "accounts/XXXXXX",
  "createTime": "2021-04-30T21:32:49.804Z",
  "updateTime": "2021-04-30T21:32:49.804Z",
  "displayName": "Test Property",
  "industryCategory": "FINANCE",
  "timeZone": "America/Los_Angeles",
  "currencyCode": "USD"
}

Management API v3 요청

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

Management API v3 응답

{
  "id": "UA-XXXXXX-3",
  "kind": "analytics#webproperty",
  "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
  "accountId": "XXXXXX",
  "internalWebPropertyId": "XXXXXX",
  "name": "Test 2",
  "websiteUrl": "YOUR-WEBSITE-URL",
  "level": "STANDARD",
  "profileCount": 0,
  "industryVertical": "FINANCE",
  "dataRetentionTtl": "MONTHS_26",
  "dataRetentionResetOnNewActivity": true,
  "permissions": {
    "effective": [
      "COLLABORATE",
      "EDIT",
      "MANAGE_USERS",
      "READ_AND_ANALYZE"
    ]
  },
  "created": "2021-05-20T05:35:51.985Z",
  "updated": "2021-05-20T05:41:39.219Z",
  "parentLink": {
    "type": "analytics#account",
    "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
  },
  "childLink": {
    "type": "analytics#profiles",
    "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
  }
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

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):
    """Retrieves the Google Analytics 4 property details."""
    client = AnalyticsAdminServiceClient()
    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}")


속성 만들기

Admin API v1의 properties.create 메서드Management API v3의 webproperties.insert 메서드와 마찬가지로, 새 Google 애널리틱스 4 속성을 만듭니다.

Admin API v1 요청

POST https://analyticsadmin.googleapis.com/v1alpha/properties?key=[YOUR_API_KEY]

{
  "displayName": "Test Property",
  "industryCategory": "AUTOMOTIVE",
  "currencyCode": "USD",
  "timeZone": "America/Los_Angeles",
  "parent": "accounts/XXXXXX"
}

Admin API v1 응답

{
  "name": "properties/XXXXXX",
  "parent": "accounts/XXXXXX",
  "createTime": "2021-05-20T09:16:08.458Z",
  "updateTime": "2021-05-20T09:16:08.458Z",
  "displayName": "Test Property",
  "industryCategory": "AUTOMOTIVE",
  "timeZone": "America/Los_Angeles",
  "currencyCode": "USD"
}

Management API v3 요청

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

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

Management API v3 응답

{
  "id": "UA-XXXXXX-3",
  "kind": "analytics#webproperty",
  "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
  "accountId": "XXXXXX",
  "internalWebPropertyId": "XXXXXX",
  "name": "Test",
  "websiteUrl": "YOUR-WEBSITE-URL",
  "level": "STANDARD",
  "profileCount": 0,
  "dataRetentionTtl": "MONTHS_26",
  "dataRetentionResetOnNewActivity": true,
  "permissions": {
    "effective": [
      "COLLABORATE",
      "EDIT",
      "MANAGE_USERS",
      "READ_AND_ANALYZE"
    ]
  },
  "created": "2021-05-20T05:35:51.985Z",
  "updated": "2021-05-20T05:35:51.985Z",
  "parentLink": {
    "type": "analytics#account",
    "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
  },
  "childLink": {
    "type": "analytics#profiles",
    "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
  }
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

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):
    """Creates a Google Analytics 4 property."""
    client = AnalyticsAdminServiceClient()
    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_)


속성 업데이트/패치

Admin API v1의 properties.patch 메서드Management API v3의 webproperties.patch 메서드와 마찬가지로, Google 애널리틱스 4 속성의 구성을 업데이트합니다.

쉼표로 구분된 업데이트 대상 필드 목록이 포함된 요청의 URL에서 updateMask 매개변수를 확인합니다. 이 목록에 없는 필드는 업데이트되지 않습니다. 클라이언트 라이브러리를 사용하는 경우, 메서드 서명의 일부로 update_mask 매개변수를 사용할 수 있습니다.

Admin API v1 요청

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

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

Admin API v1 응답

{
  "name": "properties/XXXXXX",
  "parent": "accounts/XXXXXX",
  "createTime": "2021-04-30T21:32:49.804Z",
  "updateTime": "2021-05-20T09:25:14.810Z",
  "displayName": "New Property Name",
  "industryCategory": "FINANCE",
  "timeZone": "America/Los_Angeles",
  "currencyCode": "USD"
}

Management API v3 요청

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

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

Management API v3 응답

{
  "id": "UA-XXXXXX-3",
  "kind": "analytics#webproperty",
  "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
  "accountId": "XXXXXX",
  "internalWebPropertyId": "XXXXXX",
  "name": "New Property Name",
  "websiteUrl": "XXXXXX",
  "level": "STANDARD",
  "profileCount": 0,
  "industryVertical": "FINANCE",
  "dataRetentionTtl": "MONTHS_26",
  "dataRetentionResetOnNewActivity": true,
  "permissions": {
    "effective": [
      "COLLABORATE",
      "EDIT",
      "MANAGE_USERS",
      "READ_AND_ANALYZE"
    ]
  },
  "created": "2021-05-20T05:35:51.985Z",
  "updated": "2021-05-20T05:41:39.219Z",
  "parentLink": {
    "type": "analytics#account",
    "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
  },
  "childLink": {
    "type": "analytics#profiles",
    "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
  }
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

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):
    """Updates the Google Analytics 4 property."""
    client = AnalyticsAdminServiceClient()
    # 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_)


사용자 관리

Admin API v1 알파는 현재 Management API v3와 유사한 사용자 권한 모델을 구현합니다. 예정된 Admin API 출시에서 사용자 권한 관리 기능이 크게 변경될 수도 있습니다.

Management API v3와 마찬가지로, 사용자와 계정 또는 Google 애널리틱스 4 속성 간의 연결을 만들어 사용자 권한을 관리할 수 있습니다. userLink 항목에는 사용자 ID(이메일 주소)와 사용자에게 부여된 권한 목록이 포함되어 있습니다. 사용자 연결 항목은 업데이트 또는 삭제할 수 있습니다.

다음과 같이 Admin API v1에서 사용되는 권한 이름은 Management API v3의 권한 이름과 다르지만 의미는 비슷하게 유지됩니다.

Admin API v1 권한 이름 Management API v3 권한 이름
predefinedRoles/read READ_AND_ANALYZE
predefinedRoles/collaborate COLLABORATE
predefinedRoles/edit EDIT
predefinedRoles/manage-users MANAGE_USERS

Admin API v1의 accounts.userLinks.list 메서드Management API v3의 accountUserLinks.list 메서드와 마찬가지로, 계정의 모든 사용자 연결을 나열합니다.

Admin API v1 요청

GET https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/userLinks?key=[YOUR_API_KEY]

Admin API v1 응답

{
  "userLinks": [
    {
      "name": "accounts/XXXXXX/userLinks/XXXXXX",
      "emailAddress": "XXXXXX",
      "directRoles": [
        "predefinedRoles/edit",
        "predefinedRoles/manage-users"
      ]
    }
  ]
}

Management API v3 요청

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

Management API v3 응답

{
  "kind": "analytics#entityUserLinks",
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 1000,
  "items": [
    {
      "id": "XXXXXX:XXXXXX",
      "kind": "analytics#entityUserLink",
      "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:XXXXXX",
      "entity": {
        "accountRef": {
          "id": "XXXXXX",
          "kind": "analytics#accountRef",
          "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
          "name": "This is a test account"
        }
      },
      "userRef": {
        "kind": "analytics#userRef",
        "id": "XXXXXX",
        "email": "XXXXXX"
      },
      "permissions": {
        "effective": [
          "COLLABORATE",
          "EDIT",
          "MANAGE_USERS",
          "READ_AND_ANALYZE"
        ],
        "local": [
          "EDIT",
          "MANAGE_USERS"
        ]
      }
    }
  ]
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

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

def list_account_user_links(account_id):
    """Lists user links under the specified parent account."""
    client = AnalyticsAdminServiceClient()
    results = client.list_user_links(parent=f"accounts/{account_id}")

    print("Result:")
    for user_link in results:
        print(user_link)
        print()


Admin API v1의 accounts.userLinks.list 메서드Management API v3의 accountUserLinks.update 메서드와 마찬가지로, 계정의 사용자 연결을 업데이트합니다.

Admin API v1 요청

PATCH https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/userLinks/104236685715552897132?key=[YOUR_API_KEY]

{
  "directRoles": [
    "predefinedRoles/edit",
    "predefinedRoles/manage-users"
  ]
}

Admin API v1 응답

{
  "name": "accounts/XXXXXX/userLinks/104236685715552897132",
  "emailAddress": "USER-EMAIL",
  "directRoles": [
    "predefinedRoles/edit",
    "predefinedRoles/manage-users"
  ]
}

Management API v3 요청

PUT https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX%3A104236685715552897132?key=[YOUR_API_KEY]

{
  "entity": {
    "accountRef": {
      "id": "XXXXXX"
    }
  },
  "userRef": {
    "email": "XXXXXX"
  },
  "permissions": {
    "local": [
      "EDIT",
      "MANAGE_USERS"
    ]
  }
}

Management API v3 응답

{
  "id": "XXXXXX:104236685715552897132",
  "kind": "analytics#entityUserLink",
  "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:104236685715552897132",
  "entity": {
    "accountRef": {
      "id": "XXXXXX",
      "kind": "analytics#accountRef",
      "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
      "name": "This is a test account"
    }
  },
  "userRef": {
    "kind": "analytics#userRef",
    "id": "104236685715552897132",
    "email": "XXXXXX"
  },
  "permissions": {
    "effective": [
      "COLLABORATE",
      "EDIT",
      "MANAGE_USERS",
      "READ_AND_ANALYZE"
    ],
    "local": [
      "EDIT",
      "MANAGE_USERS"
    ]
  }
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import UserLink

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 user link ID (e.g. "123456") before running the sample.
    account_user_link_id = "YOUR-ACCOUNT-USER-LINK-ID"

    update_account_user_link(account_id, account_user_link_id)

def update_account_user_link(account_id, account_user_link_id):
    """Updates the account user link."""
    client = AnalyticsAdminServiceClient()
    # This call updates the email address and direct roles of the user link.
    # The user link to update is specified in the `name` field of the `UserLink`
    # instance.
    user_link = client.update_user_link(
        user_link=UserLink(
            name=f"accounts/{account_id}/userLinks/{account_user_link_id}",
            direct_roles=["predefinedRoles/collaborate"],
        ),
    )

    print("Result:")
    print(user_link)


Admin API v1의 accounts.userLinks.create 메서드Management API v3의 accountUserLinks.insert 메서드와 마찬가지로, 계정에 사용자 연결을 만듭니다.

Admin API v1 요청

POST https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/userLinks?key=[YOUR_API_KEY]

{
  "directRoles": [
    "predefinedRoles/edit",
    "predefinedRoles/manage-users"
  ],
  "emailAddress": "USER-EMAIL"
}

Admin API v1 응답

{
  "name": "accounts/XXXXXX/userLinks/104236685715552897132",
  "emailAddress": "USER-EMAIL",
  "directRoles": [
    "predefinedRoles/edit",
    "predefinedRoles/manage-users"
  ]
}

Management API v3 요청

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

{
  "entity": {
    "accountRef": {
      "id": "XXXXXX"
    }
  },
  "userRef": {
    "email": "XXXXXX"
  },
  "permissions": {
    "local": [
      "EDIT",
      "MANAGE_USERS"
    ]
  }
}

Management API v3 응답

{
  "id": "XXXXXX:114236685715552897132",
  "kind": "analytics#entityUserLink",
  "selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:114236685715552897132",
  "entity": {
    "accountRef": {
      "id": "XXXXXX",
      "kind": "analytics#accountRef",
      "href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
      "name": "This is a test account"
    }
  },
  "userRef": {
    "kind": "analytics#userRef",
    "id": "114236685715552897132",
    "email": "XXXXXX"
  },
  "permissions": {
    "effective": [
      "COLLABORATE",
      "EDIT",
      "MANAGE_USERS",
      "READ_AND_ANALYZE"
    ],
    "local": [
      "EDIT",
      "MANAGE_USERS"
    ]
  }
}

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import CreateUserLinkRequest
from google.analytics.admin_v1alpha.types import UserLink

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_user_link(account_id, email_address)

def create_account_user_link(account_id, email_address):
    """Creates a user link for the account."""
    client = AnalyticsAdminServiceClient()
    user_link = client.create_user_link(
        CreateUserLinkRequest(
            parent=f"accounts/{account_id}",
            user_link=UserLink(
                email_address=email_address, direct_roles=["predefinedRoles/read"]
            ),
            notify_new_user=True,
        )
    )

    print("Result:")
    print(user_link)


일괄 처리

Admin API v1은 Management API v3와 달리, 멀티파트/혼합 콘텐츠를 통한 여러 Google 애널리틱스 API 호출의 일괄 처리를 지원하지 않습니다.

대신 API 수준에서는 일괄 처리가 명시적으로 지원됩니다. Admin API v1의 다음 메서드는 일괄 처리 기능을 지원합니다.

클라이언트 라이브러리를 사용하여 Admin API v1을 호출하기 위한 샘플 코드는 다음과 같습니다.

Python

from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import BatchCreateUserLinksRequest
from google.analytics.admin_v1alpha.types import CreateUserLinkRequest
from google.analytics.admin_v1alpha.types import UserLink

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_user_link(account_id, email_address)

def batch_create_account_user_link(account_id, email_address):
    """Creates a user link for the account using a batch call."""
    client = AnalyticsAdminServiceClient()
    response = client.batch_create_user_links(
        BatchCreateUserLinksRequest(
            parent=f"accounts/{account_id}",
            requests=[
                CreateUserLinkRequest(
                    user_link=UserLink(
                        email_address=email_address,
                        direct_roles=["predefinedRoles/read"],
                    )
                )
            ],
            notify_new_users=True,
        )
    )

    print("Result:")
    for user_link in response.user_links:
        print(user_link)
        print()


API 할당량 변경사항

Admin API v1에서는 Management API v3에 비해 덜 제한적인 할당량을 사용합니다.

  • Admin API v1에 대한 요청 수는 GCP 프로젝트에서 기본적으로 분당 요청 600개로 제한됩니다.
  • 현재 GCP 프로젝트당 Admin API v1 호출 수에는 일일 한도 할당량이 없습니다. 이론적으로 가능한 일일 최대 요청 수는 분당 요청 할당량으로 제한됩니다.
  • 일일 쓰기 작업 수에 대한 별도 제한은 없어졌습니다.