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

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

クエリキー

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

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

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

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

ページネーション

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

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

統合

多くの場合、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"

タイプでフィルタ

アクション タイプで制限するには、フィールド名 detail.action_detail_case に「has」演算子（:）を付けて適用します。単数形の値か、使用できるアクション タイプのリストを丸かっこで囲んでスペースで区切って指定します。アクション タイプの一覧については、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"
}