Google Drive Activity API でリクエストを行う

このガイドでは、Google Drive Activity API で activity.query メソッドを使用してリクエストを行う方法について説明します。

クエリキー

アクティビティをリクエストする方法には、Google ドライブのアイテム単位と、フォルダ階層下のすべてのアイテム用の 2 種類があります。

  • itemName: このキーの形式は「items/ITEM_ID」です。これは通常 Google ドライブ内のファイルです。このキーのフォルダを指定すると、フォルダが作成された時点や名前が変更された時点など、フォルダのアクティビティが表示されます。

  • ancestorName: このキーの形式は「items/ITEM_ID」です。レスポンスには、このフォルダの下のサブツリー内のすべてのアイテムに対するアクティビティが含まれます。

キーが設定されていない場合、デフォルトで「items/root」の ancestorName が使用され、ドライブ内のすべてのアイテムのアクティビティが表示されます。

ページネーション

pageSize フィールドを使用すると、各レスポンスで返すアクティビティのおおよその数をリクエストできます。実際に返されるアクティビティの数は異なるため、アプリはレスポンス内の任意の数を処理する必要があります。

ページサイズには制限があります。アプリで多くのアクティビティが必要な場合は、pageSize に大きな値を設定するのではなく、ページ分けを使用して複数のリクエストを行います。特に、取得するアクティビティの数がレスポンスに含まれるものより多い可能性がある場合、レスポンスには nextPageToken も含まれます。さらに結果を取得するには、同じリクエストを繰り返しますが、前のレスポンスの nextPageToken の値を持つ pageToken フィールドを追加します。

統合

多くの場合、Action オブジェクトはグループ化され、1 つの DriveActivity リソース内で返されます。一部の Action のグループ化は自然発生的に行われます。たとえば、アイテムを共有フォルダに移動すると、権限の変更がトリガーされます。

リクエストで ConsolidationStrategy（集計やバッチ処理とも呼ばれます）を指定することもできます。これにより、複数のアクターが 1 つのアイテムを編集したり、1 つの Actor が複数のファイルを新しいドライブ フォルダに移動したりするなど、関連する Action オブジェクトの他のグループ化が可能になります。

個々の Action には 1 つの Actor と 1 つの Target がありますが、グループ化すると、生成される DriveActivity は複数のアクターと複数のターゲットを持つことができます。ただし、グループ化した後でも、リクエストされた統合戦略に応じて、DriveActivity リソース内のすべてのアクションのうち代表的な、または最も重要な「プライマリ」アクションが常に存在します。

その結果、多くのクライアントは、統合が有効になっているかどうかにかかわらず、DriveActivity リソースの最上位コンテンツ（primaryActionDetail 内の集合的なアクターやターゲットなど）のみを表示し、レスポンスの詳細なアクションは無視するだけで十分である可能性があります。

フィルタ

activity.query リクエストで filter 文字列を作成すると、DriveActivity リソースで返されるアクションを制限できます。time と detail.action_detail_case の 2 つのフィールドがサポートされています。

時間でフィルタする

期間でアクションを制限するには、日付値の数値演算子を使用してフィールド名 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 を適用します。1 つの値を使用するか、かっこで囲んだスペースで区切られた使用可能なアクション タイプのリストを使用します。アクション タイプのリストを確認するには、ActionDetail オブジェクトをご覧ください。

レスポンスからアクション タイプを除外するには、フィルタ文字列の先頭にハイフン（-）を追加します。

アクション タイプの例を次に示します。

  • detail.action_detail_case:RENAME
  • detail.action_detail_case:(CREATE RESTORE)
  • -detail.action_detail_case:MOVE

組み合わせ

これらのフィルタ条件は、次のように 1 つの filter 文字列内で組み合わせることができます。

  • detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

リクエストの例

ドライブのアイテムに対する最近の 10 件のアクティビティをリクエストする:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

祖先フォルダの下にあるすべてのドライブのアイテムの統合アクティビティをリクエストします。

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

ドライブのアイテムに対するすべての MOVE と RENAME の操作をリクエストするには:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

2018 年 1 月 1 日（EST）以降のすべてのアクティビティをリクエストする:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

2017 年 6 月 UTC 中の EDIT アクションを除くすべてのアクティビティをリクエストする場合:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}