本頁面由 Cloud Translation API 翻譯而成。

目標對象匯出基礎知識

Google Analytics (分析) 4 中的目標對象可讓您根據貴商家重視的方式區隔使用者。有了目標對像功能，您可以根據共用屬性，將網站或應用程式的使用者分組。

您可以使用 Google Analytics (分析) Data API v1 產生目標對象匯出，其中包括目標對像中使用者的數據匯報。

建立目標對象匯出

Google Analytics (分析) Data API v1 採用非同步方式建立目標對象匯出項目。首先，您必須對 audienceExports.create 方法提出要求，才能建立使用者目標對象匯出內容。然後，系統會使用 audienceExports.query 方法擷取目標對像中的使用者。

此外，您可以使用 audienceExports.get 擷取特定目標對象匯出作業的設定中繼資料，並使用 audienceExports.list 列出資源的所有目標對象匯出作業。

選取檢舉實體

所有 Data API v1 方法都需要 Google Analytics (分析) 4 資源 ID，在網址要求路徑內指定，格式為 properties/GA4_PROPERTY_ID，例如：

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

報表是根據指定 Google Analytics (分析) 4 資源中收集到的 Google Analytics (分析) 事件資料產生。

如果您使用其中一個 Data API 用戶端程式庫，則不需要手動操控要求網址路徑。多數 API 用戶端提供的 property 參數預期字串格式為 properties/GA4_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"
  }
}

查詢目標對象匯出完備性狀態

呼叫 audienceExports.create 後，系統可能需要幾分鐘的時間才能產生目標對象匯出內容。您可以呼叫 audienceExports.get 方法，取得目標對象匯出的完備性狀態。

請使用 audienceExports.create 回應提供的目標對象匯出名稱 (例如 properties/1234567/audienceExports/123)，指定目標對象匯出項目。

示例：

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.create 方法建立目標對象匯出作業後，請呼叫 audienceExports.query 方法，並指定目標對象匯出項目名稱 (例如 properties/1234567/audienceExports/123)。

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
}

目標對象匯出資料預期

下一節將說明目標對象匯出功能對於使用者成員資格的預期資料。

資料更新間隔

「目標對象匯出資料」資料更新間隔是指 Google Analytics (分析) 收集事件、處理事件，然後在目標對像中更新使用者成員資格所需的時間。如果這個過程需時 24 小時，目標對象匯出資料的更新間隔為 24 小時。詳情請參閱資料更新間隔。

舉例來說，如果使用者完成第一筆購物，之後又 7 小時後，您為「購買者」目標對象建立目標對象匯出項目，就幾乎可以確定使用者還未納入「購買者」目標對象匯出作業。初次購買後的 14 到 38 小時內，該使用者可能會匯出到新的目標對象匯出檔案。

目標對象匯出是數據匯報

目標對象匯出功能是快照中目標對象的一份使用者名單。如果是 Google Ads 再行銷，Google Analytics (分析) 會自動並持續將目標對像中的使用者匯出至 Google Ads。相較之下，如果是使用 Data API v1 建立的目標對象匯出，則必須建立新的目標對象匯出，才能查看該目標對像中的最新使用者。

目標對象匯出是根據可用最新使用者成員資格建立而成。不過，目標對象匯出作業可能只有 20 小時的資料更新間隔，這表示目標對象匯出作業將以目前時間前 20 小時的所有事件為依據。

最新的會員資料每天會更新一次，通常在資源所在時區的白天時段更新。這表示在上午 9 點和 11 點針對同一目標對象匯出目標對象，可能會傳回相同的資料，但對於下午 3 點的匯出目標對象，可能會因納入額外一天的資料而不同。

目標對象匯出期限

目標對象匯出會在 72 小時後過期。新使用者每天可能會進入並退出目標對象。如要取得最新使用者數據匯報，您必須每天建立新的目標對象匯出項目。

目標對象匯出使用者限制

如果目標對像或資源的大小超過使用者限制，目標對象匯出就會傳回目標對象的代表性樣本。這些限制取決於資源類型 (例如標準或 360 資源)，且會在每個目標對象匯出作業中個別強制執行。回訪者是指符合要求目標對象的使用者，且視為使用者，可能不是目標對象成員。

限制類型	標準資源限制	Analytics (分析) 360 資源限制
回訪使用者人數上限	200 萬	2 億
考慮到的使用者人數上限	1000 萬	10 億

報表識別資訊一致性

報表識別資訊會決定報表中重複計算使用者的方式。目標對象匯出不會根據報表識別資訊設定變更。目標對象匯出功能一律會先根據 User-ID 和裝置 ID 來識別使用者。

這表示目標對象報表顯示的使用者數量，可能會比目標對象匯出報表傳回的使用者人數多。舉例來說，如果報表識別資訊是「以裝置為基礎」，且收集了使用者 ID，則報表不會根據使用者 ID 刪除重複的使用者，但目標對象匯出作業會根據使用者 ID 來簡化。

補充作業一致性

如果您在 Google Analytics (分析) 中建立目標對象，並啟用 Google Ads 再行銷，Google Analytics (分析) 會將近期新增的成員回補至 Google Ads 中的該目標對象。不過，Google Analytics (分析) 報表和目標對象匯出「不包含」回補的目標對象成員。建立目標對象後，使用者必須記錄事件，報表和目標對象匯出作業才會顯示該目標對像中的使用者。

舉例來說，如果使用者在 6 月 20 日記錄購買事件，而您在 6 月 21 日建立「購買者」目標對象，可能要等到 6 月 22 日才會在新的目標對象匯出中看到該使用者。但是，只有在使用者於 6 月 21 日記錄任何事件的情況下，該使用者才會出現在目標對象匯出作業中。