이 가이드에서는 activity.query 메서드를 사용하여 Google Drive Activity API에서 요청하는 방법을 설명합니다.
쿼리 키
활동을 요청하는 방법에는 Google Drive 항목별로 요청하는 방법과 폴더 계층 아래의 모든 항목을 요청하는 방법이 있습니다.
itemName: 이 키의 형식은 'items/ITEM_ID'입니다. 일반적으로 Drive의 파일입니다. 이 키에 폴더를 지정하면 폴더가 생성되었거나 이름이 변경된 시점과 같은 폴더 활동이 표시됩니다.
ancestorName: 이 키의 형식은 'items/ITEM_ID'이며 응답에는 이 폴더 아래의 하위 트리에서 모든 항목에 대한 활동이 포함됩니다.
키가 설정되지 않으면 기본적으로 'items/root'의 ancestorName를 사용하고 Drive의 모든 항목에 대한 활동을 표시합니다.
페이지로 나누기
pageSize 필드를 사용하면 각 응답에서 반환할 대략적인 활동 수를 요청할 수 있습니다. 반환된 활동의 실제 수는 다르므로 앱은 응답에서 임의의 수량을 처리해야 합니다.
페이지 크기는 제한적입니다. 앱에 활동이 많이 필요한 경우 pageSize에 큰 값을 설정하는 대신 페이징을 사용하여 여러 번 요청합니다.
특히 가져올 활동이 응답에 포함된 것보다 많을 수 있는 경우 응답에 nextPageToken도 포함됩니다. 더 많은 결과를 검색하려면 동일한 요청을 반복하되 이전 응답의 값이 nextPageToken인 pageToken 필드를 추가합니다.
통합
Action 객체는 단일 DriveActivity 리소스 내에 그룹화되어 반환되는 경우가 많습니다. 항목을 공유 폴더로 이동하여 권한 변경을 트리거하는 등 일부 Action 그룹은 자연스럽게 발생합니다.
요청에서 ConsolidationStrategy(집계 또는 일괄 처리라고도 함)를 지정할 수도 있습니다. 이렇게 하면 여러 행위자가 하나의 항목을 수정하거나 하나의 Actor가 여러 파일을 새 Drive 폴더로 이동하는 등 관련 Action 객체를 다른 방식으로 그룹화할 수 있습니다.
개별 Action에는 Actor 1개와 Target 1개가 있지만 그룹화 후에는 결과 DriveActivity에 여러 행위자와 여러 타겟이 있을 수 있습니다.
그러나 그룹화한 후에도 요청된 통합 전략에 따라 DriveActivity 리소스의 모든 작업을 대표하거나 가장 중요한 '기본' 작업이 항상 있습니다.
따라서 통합 여부와 관계없이 많은 클라이언트는 DriveActivity 리소스의 최상위 콘텐츠 (예: primaryActionDetail 내의 집합적 행위자 및 타겟)만 보고 응답의 세부 작업은 무시해도 충분할 수 있습니다.
필터
activity.query 요청에서 filter 문자열을 구성하여 DriveActivity 리소스에 반환될 수 있는 작업을 제한할 수 있습니다. 지원되는 필드는 time 및 detail.action_detail_case 두 가지입니다.
시간별 필터링
기간별로 작업을 제한하려면 날짜 값에 숫자 연산자를 사용하여 필드 이름 time를 지정하고 선택사항인 'AND'로 연결합니다. 1970년 1월 1일 이후 밀리초 또는 RFC 3339 형식을 사용합니다(예:
time > 1452409200000 AND time <= 1492812924310
time >= "2016-01-10T01:02:03-05:00"
유형별 필터링
작업 유형별로 제한하려면 'has' 연산자 (:)와 함께 필드 이름 detail.action_detail_case를 적용합니다. 단일 값 또는 허용되는 작업 유형 목록을 괄호로 묶고 공백으로 구분하여 사용합니다. 작업 유형 목록을 찾으려면 ActionDetail 객체를 검토하세요.
응답에서 작업 유형을 제외하려면 필터 문자열 앞에 하이픈 (-)을 추가합니다.
다음은 몇 가지 작업 유형의 예입니다.
detail.action_detail_case:RENAME
detail.action_detail_case:(CREATE RESTORE)
-detail.action_detail_case:MOVE
Combinations
이러한 필터링 조건은 단일 filter 문자열 내에 결합할 수 있습니다(예:
detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-03-26(UTC)"],[],[],null,["# Make requests in the Google Drive Activity API\n\nThis guide explains how to make requests in the Google Drive Activity API using the\n[`activity.query`](/workspace/drive/activity/v2/reference/rest/v2/activity/query) method.\n\nQuery key\n---------\n\nThere are 2 ways to request activity: by Google Drive item, or for everything\nunderneath a folder hierarchy.\n\n- `itemName`: The format for this key is \"items/ITEM_ID\". Typically this is a\n file in Drive. If you specify a folder for this key, it shows activity\n for the folder such as when it was created or renamed.\n\n- `ancestorName`: The format for this key is \"items/ITEM_ID\", and the\n response includes activity on all items in the subtree below this\n folder.\n\nWhen no key is set, it defaults to using the `ancestorName` of \"items/root\" and\nshows activity for all items in your Drive.\n\nPagination\n----------\n\nThe `pageSize` field allows you to request an approximate number of activities\nto return in each response. The actual count of returned activities will vary,\nso your app should handle arbitrary quantities in the response.\n\nPage sizes are limited. If your app needs many activities, make multiple\nrequests using pagination instead of setting a large value for `pageSize`.\nSpecifically, if there might be more activity to fetch than what's included in\nthe response, then the response will also contain a `nextPageToken`. To retrieve\nmore results, repeat the same request but add a `pageToken` field with the value\nof `nextPageToken` from the prior response.\n\nConsolidation\n-------------\n\n[`Action`](/workspace/drive/activity/v2/reference/rest/v2/activity/action) objects are often grouped and returned within a single\n[`DriveActivity`](/workspace/drive/activity/v2/reference/rest/v2/activity/driveactivity) resource. Some `Action` groupings occur spontaneously, such as moving an\nitem into a shared folder triggering a permission change.\n\nYou can also specify a\n[`ConsolidationStrategy`](/workspace/drive/activity/v2/reference/rest/v2/activity/query#consolidationstrategy)\n(sometimes called aggregation or batching) in the request. This enables\nother groupings of related `Action` objects, such as several actors editing one\nitem, or one [`Actor`](/workspace/drive/activity/v2/reference/rest/v2/activity/actor) moving multiple files into a new Drive folder.\n\nWhile an individual `Action` has one `Actor` and one [`Target`](/workspace/drive/activity/v2/reference/rest/v2/activity/target), after grouping,\nthe resulting `DriveActivity` can have multiple actors and multiple targets.\nEven after grouping, however, there's always a \"primary\" action that's\neither representative, or the most important, of all actions in the\n`DriveActivity` resource, depending on the requested consolidation strategy.\n\nAs a result, whether or not consolidation is turned on, it might be sufficient for\nmany clients to view only the top-level contents of a `DriveActivity` resource (such as\nthe collective actors and targets within the `primaryActionDetail`) and ignore\nthe detailed actions in the response.\n\nFilters\n-------\n\nYou can restrict the actions that might be returned in the `DriveActivity`\nresource by constructing a `filter` string in the `activity.query` request. There's\n2 supported fields: `time` and `detail.action_detail_case`.\n\n### Filter by time\n\nTo restrict actions by time range, specify the field name `time` with numerical\noperators on date values, joined by an optional \"AND\". Use milliseconds since Jan 1, 1970 or the\n[RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format, such as:\n\n- `time \u003e 1452409200000 AND time \u003c= 1492812924310`\n- `time \u003e= \"2016-01-10T01:02:03-05:00\"`\n\n### Filter by type\n\nTo restrict by action type, apply the field name `detail.action_detail_case` with\nthe \"has\" operator (`:`). Use either a singular value or a list of allowed action\ntypes enclosed in parentheses, separated by a space. To find a list of action\ntypes, review the [`ActionDetail`](/workspace/drive/activity/v2/reference/rest/v2/activity/actiondetail) objects.\n\nTo exclude an action type from the response,\nprepend a hyphen (`-`) to the beginning of the filter string.\n\nHere's some action type examples:\n\n- `detail.action_detail_case:RENAME`\n- `detail.action_detail_case:(CREATE RESTORE)`\n- `-detail.action_detail_case:MOVE`\n\n### Combinations\n\nThese filtering conditions can be combined within a single `filter` string, such as:\n\n- `detail.action_detail_case:(CREATE EDIT RESTORE) time \u003e 1452409200000`\n\nExample requests\n----------------\n\n#### Request the 10 most recent activities for a Drive item:\n\n {\n \"itemName\": \"items/\u003cvar translate=\"no\"\u003eITEM_ID\u003c/var\u003e\",\n \"pageSize\": 10\n }\n\n#### Request consolidated activities for every Drive item below an ancestor folder:\n\n {\n \"ancestorName\": \"items/\u003cvar translate=\"no\"\u003eITEM_ID\u003c/var\u003e\",\n \"consolidationStrategy\": {\n \"legacy\": {}\n }\n }\n\n#### Request all `MOVE` and `RENAME` actions on a Drive item:\n\n {\n \"itemName\": \"items/\u003cvar translate=\"no\"\u003eITEM_ID\u003c/var\u003e\",\n \"filter\": \"detail.action_detail_case:(MOVE RENAME)\"\n }\n\n#### Request all activity since January 1, 2018 EST:\n\n {\n \"ancestorName\": \"items/root\",\n \"filter\": \"time \u003e= \\\"2018-01-01T00:00:00-05:00\\\"\"\n }\n\n#### Request all activity, except `EDIT` actions, during June 2017 UTC:\n\n {\n \"ancestorName\": \"items/root\",\n \"filter\": \"time \u003e= \\\"2018-06-01T00:00:00Z\\\" time \u003c \\\"2018-07-01T00:00:00Z\\\" -detail.action_detail_case:EDIT\"\n }"]]
