Reports API: エンティティ使用状況レポート

エンティティ使用状況レポートは、アカウントのユーザーが使用しているエンティティに関連する Google Workspace サービス アクティビティを返します。これらのレポートは、特定の使用状況情報に合わせてカスタマイズしたり、フィルタリングしたりできます。過去 30 日間のデータを使用できます。

エンティティ使用状況レポートは、顧客契約に従い、合法的な目的のためにのみ使用できます。これらのレポートは、Google Workspace と Google for Education にも適用されます。

すべてのエンティティの使用状況アクティビティを取得する

現在、この API でサポートされているエンティティ タイプは Google+ コミュニティのみです。アカウント内のアプリ エンティティに関連するすべてのアクティビティのレポートを取得するには、次の GET HTTP リクエストを使用し、承認に関するドキュメントに記載されている認証トークンを含めます。次の例では、読みやすくするために改行を挿入しています。

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

date 値は使用が発生した日付で、タイムスタンプは ISO 8601 形式(yyyy-mm-dd)です。これには、アカウントのタイムゾーンを使用することをおすすめします。クエリ文字列パラメータとレスポンス プロパティの詳細については、API リファレンスをご覧ください。エンティティの使用状況レポートのパラメータの詳細については、エンティティの使用状況パラメータのリファレンスをご覧ください。

applicationParameters は、取得するパラメータのカンマ区切りのリストです。各パラメータは application:parameter_name としてフォーマットされます(例: gplus:community_name)。使用可能なパラメータについては、エンティティの使用パラメータのリファレンスをご覧ください。パラメータが指定されていない場合は、すべてが返されます。

parameterFilters は、結果に適用するフィルタのカンマ区切りのリストです。各フィルタの形式は application:parameter_name[relational_operator]parameter_value です。たとえば、フィルタ gplus:num_total_members>100 は、gplus:num_total_members パラメータの値が 100 より大きい結果のみが含まれるように結果をフィルタリングします。

maxResults は、1 回の取得で返される結果の最大数です。結果の合計数がこれより大きい場合、レスポンスは切り捨てられ、nextPageToken が含まれます(以下の JSON レスポンスの例をご覧ください)。

次の例では、すべての gplus_communities エンティティのすべてのパラメータを含むレポートを取得します。

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11

次の例では、すべての gplus_communities エンティティの community_name パラメータを含むレポートを取得します。

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name

次の例では、メンバーが 100 人を超えるコミュニティでフィルタされた、gplus_communities エンティティごとに community_namenum_total_members のレポートを取得します。API レスポンスの例については、JSON レスポンスの例をご覧ください。

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11
?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100

特定のエンティティのレポートを取得する

特定のエンティティのレポートを取得するには、次の GET HTTP リクエストを使用して、承認のドキュメントで説明されている認証トークンを含めます。次の例では、読みやすくするために改行を挿入しています。

GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

entityKey は、エンティティが存在するアプリケーションに固有のエンティティ ID です。対象エンティティの entityKey を取得する方法の詳細については、API リファレンスをご覧ください。その他のパラメータについては、上記の エンティティの使用状況をすべて取得するをご覧ください。

クエリ文字列パラメータとレスポンス プロパティの詳細については、API リファレンスをご覧ください。エンティティの使用状況レポートのパラメータの詳細については、エンティティの使用状況パラメータのリファレンスをご覧ください。

次の例では、entityKey が「1234」である gplus_community エンティティのエンティティ レポートを取得します。

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

使用状況レポートの JSON レスポンスの例

成功すると、HTTP 200 のステータス コードが返されます。レスポンスでステータス コードとともにレポートが返されます。読みやすくするために、レスポンスの一部のパラメータは省略しています。

エンティティ レポートの JSON レスポンスの例

{
 "kind": "reports#usageReports",
 "nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA",
 "usageReports": [
 {
   "kind": "admin#reports#usageReport",
   "date": "2017-12-11",
   "entity": {
    "type": "OBJECT",
    "customerId": "C03az79cb",
    "objectType": "GPLUS_COMMUNITY",
    "objectId": "1234",
   },
   "parameters": [
    {
      "name": "gplus:community_name",
      "stringValue": "My Community"
    },
    {
     "name": "gplus:num_total_members",
     "intValue": 37
    },
    {
     "name": "gplus:num_7day_active_members",
     "intValue": 12
    },
    {
     "name": "gplus:num_30day_active_members",
     "intValue": 17
    },
   ]
  }
 ]
}

警告付きのエンティティ レポートの JSON レスポンスの例

リクエストを完了できない場合、レスポンスで 1 つ以上の警告が返されることがあります。この例では、リクエストが行われた時点ではレポートを利用できません。
{
 "kind": "reports#usageReports",
 "warnings": [
    {
      "code": "PARTIAL_DATA_AVAILABLE"
      "message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours."
      "data": [
        {
          "key": "date"
          "value": "2017-12-11"
        }
      ]
    }
  ],
 "usageReports": [],
}
warnings 配列の各エントリには次のパラメータがあります。
  • code: 機械が読み取れる警告コード。
  • message: 人が読める形式の警告メッセージ
  • data: 詳細な警告情報を提供する Key-Value ペアのリスト。