잠재고객 내보내기 만들기
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google 애널리틱스의 잠재고객을 사용하면 비즈니스에 중요한 방식으로 사용자를 분류할 수 있습니다. 잠재고객을 사용하면 공유 속성을 기반으로 사이트 또는 애플리케이션의 사용자를 그룹화할 수 있습니다.
Data API를 사용하여 사용자의 스냅샷을 포함한 잠재고객을 내보낼 수 있습니다.
잠재고객 내보내기에 표시되는 데이터에 관한 중요한 정보는 잠재고객 내보내기 데이터 기대치 가이드를 참고하세요.
개요
다음 Data API 요청을 실행하여 잠재고객 내보내기를 만들고 쿼리합니다.
audienceExports.create 메서드를 호출하여 잠재고객 내보내기를 만듭니다.audienceExports.query 메서드를 호출하면 잠재고객의 사용자를 검색할 수 있습니다.
자세한 내용은 audienceExports.get를 호출하여 특정 잠재고객 내보내기에 관한 구성 메타데이터를 검색하고 audienceExports.list를 호출하여 특정 속성의 모든 잠재고객 내보내기를 나열하면 됩니다.
보고 항목 선택
모든 Data API 메서드에는 Google 애널리틱스 속성 식별자를 URL 요청 경로 내에 properties/GA_PROPERTY_ID 형식으로 지정해야 합니다. 예를 들면 다음과 같습니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports
이 보고서는 지정된 Google 애널리틱스 속성에서 수집된 Google 애널리틱스 이벤트 데이터를 기반으로 생성됩니다.
Data API 클라이언트 라이브러리 중 하나를 사용하는 경우 요청 URL 경로를 변경할 필요가 없습니다. 대부분의 API 클라이언트는 properties/GA_PROPERTY_ID 형식의 문자열을 예상하는 property 매개변수를 제공합니다. 클라이언트 라이브러리 사용 예는 빠른 시작 가이드를 참고하세요.
잠재고객 내보내기 만들기
잠재고객 내보내기를 만들려면 요청에서 AudienceExport 객체를 사용하여 audienceExports.create 메서드를 호출합니다. 다음 매개변수가 필요합니다.
audience 필드의 유효한 잠재고객 이름으로 형식이 properties/{propertyId}/audiences/{audienceId}입니다. Google 애널리틱스 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
}
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-26(UTC)
[null,null,["최종 업데이트: 2025-07-26(UTC)"],[[["\u003cp\u003eGoogle Analytics Audiences allows you to segment users based on shared attributes, enabling targeted analysis and marketing efforts.\u003c/p\u003e\n"],["\u003cp\u003eYou can export audience data, including user snapshots, using the Data API, specifically the \u003ccode\u003eaudienceExports.create\u003c/code\u003e and \u003ccode\u003eaudienceExports.query\u003c/code\u003e methods.\u003c/p\u003e\n"],["\u003cp\u003eBefore querying, you should check the audience export's readiness state using the \u003ccode\u003eaudienceExports.get\u003c/code\u003e method to ensure data is available.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eaudienceExports.list\u003c/code\u003e method lets you view all your audience exports for a given property, while \u003ccode\u003eaudienceExports.query\u003c/code\u003e retrieves the actual user data.\u003c/p\u003e\n"]]],["Google Analytics audiences can be segmented and exported via the Data API. To export, first, call `audienceExports.create` with a valid audience name and dimensions. Then, use `audienceExports.get` to check the export's readiness (`CREATING` or `ACTIVE`). Once `ACTIVE`, retrieve users with `audienceExports.query` using the export's name. You can use `audienceExports.list` to view all exports and use the format `properties/GA_PROPERTY_ID` when specifying the property ID.\n"],null,["# Create an audience export\n\n[Audiences in Google Analytics](//support.google.com/analytics/answer/9267572)\nlet you segment your users in the ways that are important to your business. With\naudiences, you can group users of your site or application based on shared\nattributes.\n\nYou can export your audiences, including a snapshot of their users, using the\n[Data API](/analytics/devguides/reporting/data/v1/rest).\n\nRefer to the [Audience export data expectations](/analytics/devguides/reporting/data/v1/audience-export-expectations)\nguide for important information about the data you see in audience exports.\n\nOverview\n--------\n\nMake the following Data API requests to create and query an audience export:\n\n1. Call the [`audienceExports.create`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/create) method to create an audience export.\n2. Call the [`audienceExports.query`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/query) method is used to retrieve the users in the audience.\n\nFor more information, you can call\n[`audienceExports.get`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/get) to\nretrieve configuration metadata about a specific audience export, and\n[`audienceExports.list`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/list) to\nlist all your audience exports for a specific property.\n\nSelect a reporting entity\n-------------------------\n\nAll Data API methods require the [Google Analytics property\nidentifier](/analytics/devguides/reporting/data/v1/property-id) to be specified inside a URL request path, in the\nform of `properties/GA_PROPERTY_ID`. Here's an example: \n\n POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports\n\nThe report is generated based on the Google Analytics event data collected in\nthe specified Google Analytics property.\n\nIf you're using one of the [Data API client libraries](/analytics/devguides/reporting/data/v1/client-libraries), you\ndon't need to change the request URL path. Most API clients provide a `property`\nparameter that expects a string in the form of `properties/GA_PROPERTY_ID`. See\n[Quick start guide](/analytics/devguides/reporting/data/v1/quickstart-client-libraries) for examples of using the\nclient libraries.\n\nCreate an audience export\n-------------------------\n\nTo create an audience export, call the [`audienceExports.create`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/create) method using the\n[`AudienceExport`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports#AudienceExport)\nobject in your request. The following parameters are required:\n\n- A valid audience name in the [`audience`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports#AudienceExport.FIELDS.audience) field, formatted as `properties/{propertyId}/audiences/{audienceId}`. You can use the [`audiences.list`](/analytics/devguides/config/admin/v1/rest/v1alpha/properties.audiences/list) method of the Google Analytics Admin API v1 to obtain this value. The [`Audience.name`](/analytics/devguides/config/admin/v1/rest/v1alpha/properties.audiences#Audience.FIELDS.name) field of the `audiences.list` response contains the audience name.\n- A valid list of dimensions in the [`dimensions`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports#AudienceExport.FIELDS.dimensions) field. The list of dimensions supported by this method can be found in the [Audience export schema](/analytics/devguides/reporting/data/v1/audience-export-api-schema) documentation. Only the data for dimensions mentioned in this field is included in an audience export.\n\nHere's a sample request to create an audience export: \n\n### HTTP Request\n\n POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports\n {\n \"audience\": \"properties/1234567/audiences/12345\",\n \"dimensions\": [\n {\n \"dimensionName\": \"deviceId\"\n }\n ]\n }\n\nA response of the `audienceExports.create` method contains the audience export's\nname in the `name` field, for example `properties/1234567/audienceExports/123`.\nHere's a sample response: \n\n### HTTP Response\n\n {\n \"response\": {\n \"@type\": \"type.googleapis.com/google.analytics.data.v1alpha.AudienceExport\",\n \"name\": \"properties/1234567/audienceExports/123\",\n \"audience\": \"properties/1234567/audiences/12345\",\n \"audienceDisplayName\": \"Purchasers\",\n \"dimensions\": [\n {\n \"dimensionName\": \"deviceId\"\n }\n ],\n \"state\": \"CREATING\",\n \"beginCreatingTime\": \"2023-06-22T23:35:28.787910949Z\"\n }\n }\n\nYou can use the `name` to query the users from the audience export.\n\nQuery the audience export's readiness state\n-------------------------------------------\n\nIt might take several minutes to generate the audience export after the\n[`audienceExports.create`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/create)\ncall.\n\nYou can check the readiness state of an audience export by calling the\n[`audienceExports.get`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/get) method.\n\nUse the audience export name from an `audienceExports.create` response to\nspecify the audience export in your request.\n\nHere's a sample request: \n\n### HTTP Request\n\n GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123\n\nThe readiness state for an audience export is returned in the [`state`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports#AudienceExport.FIELDS.state) field\nof the response. Once the audience export generation is complete, its state\nchanges from `CREATING` to `ACTIVE`.\n\nHere's a sample response: \n\n### HTTP Response\n\n {\n \"name\": \"properties/1234567/audienceExports/123\",\n \"audience\": \"properties/1234567/audiences/12345\",\n \"audienceDisplayName\": \"Purchasers\",\n \"dimensions\": [\n {\n \"dimensionName\": \"deviceId\"\n }\n ],\n \"state\": \"CREATING\",\n \"beginCreatingTime\": \"2023-06-22T23:35:28.787910949Z\"\n }\n\nYou can obtain the state of all audience exports by calling the\n[`audienceExports.list`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/list)\nmethod.\n\nRetrieve users from an audience export\n--------------------------------------\n\nOnce the audience export is generated, call the [`audienceExports.query`](/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/query) method, and specify the\naudience export's `name` in the request.\n\nHere's a sample request: \n\n### HTTP Request\n\n POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query\n\nIf the audience export is ready, this call returns the list of users in the\naudience.\n\nHere's a sample response: \n\n### HTTP Response\n\n {\n \"audienceExport\": {\n \"name\": \"properties/1234567/audienceExports/123\",\n \"audience\": \"properties/1234567/audiences/12345\",\n \"audienceDisplayName\": \"Purchasers\",\n \"dimensions\": [\n {\n \"dimensionName\": \"deviceId\"\n }\n ],\n \"state\": \"ACTIVE\",\n \"beginCreatingTime\": \"2023-06-22T23:35:28.787910949Z\"\n },\n \"audienceRows\": [\n {\n \"dimensionValues\": [\n {\n \"value\": \"1000276123.1681742376\"\n }\n ]\n },\n {\n \"dimensionValues\": [\n {\n \"value\": \"1000374452.1668627377\"\n }\n ]\n },\n {\n \"dimensionValues\": [\n {\n \"value\": \"1000391956.1652750758\"\n }\n ]\n },\n {\n \"dimensionValues\": [\n {\n \"value\": \"1000410539.1682018694\"\n }\n ]\n },\n {\n \"dimensionValues\": [\n {\n \"value\": \"1000703969.1666725875\"\n }\n ]\n }\n ],\n \"rowCount\": 5\n }"]]
