建立目標對象匯出作業

Google Analytics 中的目標對象 可讓您根據自家業務需求區隔使用者。您可以根據共用屬性，將網站或應用程式的使用者分組，建立目標對象。

您可以使用 Data API 匯出目標對象，包括使用者快照。

請參閱目標對象匯出資料預期指南，瞭解目標對象匯出作業中顯示的資料相關重要資訊。

總覽

提出下列 Data API 要求，建立及查詢目標對象匯出作業：

  1. 呼叫 audienceExports.create 方法來建立目標對象匯出作業。
  2. 呼叫 audienceExports.query 方法，即可擷取目標對象中的使用者。

如需更多資訊，您可以呼叫 audienceExports.get，擷取特定目標對象匯出作業的設定中繼資料，並呼叫 audienceExports.list，列出特定資源的所有目標對象匯出作業。

選取報表實體

所有 Data API 方法都必須在網址要求路徑中指定 Google Analytics 資源 ID，格式為 properties/GA_PROPERTY_ID。範例如下：

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

這份報表是根據指定 Google Analytics 資源中收集的 Google Analytics 事件資料產生。

如果您使用資料 API 用戶端程式庫，則無須變更要求網址路徑。大多數 API 用戶端都會提供 property 參數，並預期字串格式為 properties/GA_PROPERTY_ID。如需使用用戶端程式庫的範例，請參閱快速入門指南。

建立目標對象匯出作業

如要建立目標對象匯出作業，請在要求中使用 AudienceExport 物件，呼叫 audienceExports.create 方法。以下是必要參數：

  • audience 欄位中有效的目標對象名稱，格式為 properties/{propertyId}/audiences/{audienceId}。您可以使用 Google Analytics Admin API v1 的 audiences.list 方法取得這個值。audiences.list 回應的 Audience.name 欄位包含目標對象名稱。
  • 「dimensions」欄位中必須有有效的維度清單。如要查看這個方法支援的維度清單，請參閱目標對象匯出架構說明文件。只有這個欄位中提及的維度資料，才會納入目標對象匯出資料。

以下是建立目標對象匯出的範例要求：

HTTP 要求

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

audienceExports.create 方法的回應會在 name 欄位中包含目標對象匯出作業的名稱，例如 properties/1234567/audienceExports/123。以下是範例回應：

HTTP 回應

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

您可以使用 name 查詢從目標對象匯出作業取得的使用者。

查詢目標對象匯出的準備狀態

通話結束後，系統可能需要幾分鐘才能產生目標對象匯出資料。audienceExports.create

您可以呼叫 audienceExports.get 方法，檢查目標對象匯出作業的就緒狀態。

使用 audienceExports.create 回應中的目標對象匯出名稱，在要求中指定目標對象匯出項目。

以下是範例要求：

HTTP 要求

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

回應的 state 欄位會傳回目標對象匯出的準備狀態。目標對象匯出作業完成後，狀態會從 CREATING 變更為 ACTIVE。

以下是範例回應：

HTTP 回應

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

您可以呼叫 audienceExports.list 方法，取得所有目標對象匯出作業的狀態。

從目標對象匯出作業中擷取使用者

產生目標對象匯出作業後，請呼叫 audienceExports.query 方法，並在要求中指定目標對象匯出作業的 name。

以下是範例要求：

HTTP 要求

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

如果目標對象匯出作業已完成，這項呼叫會傳回目標對象中的使用者清單。

以下是範例回應：

HTTP 回應

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}