認証
Enrollment Token API にアクセスするために必要な認証に関しては、ガイド(Chrome Enterprise Core's Takeout API Service Script)で詳しく説明されています。ユーザーはそれと同じ手順に従って、アクセス トークンを取得する必要があります。
ChromeEnrollmentToken
ChromeEnrollmentToken は、Chrome ブラウザの登録を識別するための文字列です。
リソース表現
Directory API の ChromeEnrollmentToken のリソースには、以下の JSON テンプレートが使用されます。
{
"kind": "admin#directory#chromeEnrollmentToken",
"orgUnitPath": string,
"token": string,
"tokenPermanentId": string,
"customerId": string,
"orgUnitPath": string,
"state": enum {
"active",
"expired",
"revoked",
}
"expiration": oneof {
"expireTime": dateTime,
"ttl": duration
}
"creatorId": string,
"creationTime": dateTime,
"revokerId": string,
"revokeTime": dateTime,
"tokenType": enum {
"chromeBrowser"
}
}
API の呼び出し
アカウントのすべての登録トークンを一覧表示する
組織部門の特定のアカウントの Chrome 登録トークンをすべて一覧表示するには、次の GET リクエストを使用し、「認証」セクションに従って取得したアクセス トークンを含めます。
注: このコードサンプルでは、読みやすくするために改行を挿入しています。
GET
https://www.googleapis.com/admin/directory/v1.1beta1/customer/
{my_customer|customerId}/chrome/enrollmentTokens?query=
{query_string}&pageSize={number_of_results_to_return}
&pageToken={page_token_from_previous_request}&orgUnitPath={/org-unit-path}
- customerId は、お客様の Google アカウントを表す一意の識別子です。
- アカウント管理者の代理としてリクエストを実行する場合は、ご自分のアカウントの customerId を表す文字列 my_customer を使用することもできます。また、ユーザー情報を取得する(Retrieve a user)操作によってcustomerId の値を取得することもできます。この操作のパスの userKey パラメータには、管理者のメールアドレスまたは管理者の一意のユーザー ID を使用します。
このリクエストで使用できるすべてのペイロード パラメータは以下のとおりです。
パラメータ | 必須 / 省略可 | 型 | 説明 |
---|---|---|---|
orgUnitPath | 省略可 | string | 特定の組織部門で作成された登録トークンのみを一覧表示します。このフィールドを指定しない場合、このお客様のすべての登録トークンが一覧表示されます。 |
pageSize | 省略可 | int | ページあたりの結果数の上限です。デフォルト値は 100 で、これは指定できる最大の値です。 |
pageToken | 省略可 | string | pageToken クエリ パラメータは、クエリ結果の次のページをリクエストする際に使用します。その次のページをリクエストする場合は、pageToken クエリ パラメータに前回のレスポンスの nextPageToken を使用します。注: pageToken を指定してリクエストする場合は、query および orgUnitPath に、pageToken を生成したリクエストと同じ値を指定する必要があります。 |
query | 省略可 | string | 一覧表示されるトークンをフィルタするための検索文字列です。query の指定方法については、以下の説明(query でのフィルタの指定方法)をご覧ください。 |
例
リクエストの例
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/chrome/enrollmentTokens?pageSize=1&orgUnitPath=”/Org-unit-path”
JSON レスポンス
リクエストが成功すると、200 番の HTTP ステータス コードが返されます。レスポンスでは、ステータス コードと一緒に Chrome 登録トークンのプロパティが返されます。
{
kind: "admin#directory#chromeEnrollmentTokens",
"chrome_enrollment_tokens": [
{
"tokenId": "token_id_value",
"tokenPermanentId": "token_Permanent_id_value",
"kind": "admin#directory#chromeEnrollmentToken",
"orgUnitPath": "/Org-unit-path",
"state": "active",
"creator_id": “unique_id_of_user",
"create_time": "2020-04-30T19:22:44Z",
"tokenType": "chromeBrowser",
}
],
"nextPageToken": "abcdefghijkl123"
}
クエリでのフィルタの指定方法
一覧表示のリクエストで query パラメータを使用する場合、結果が一致とみなされるためには、次のパラメータのいずれかにおいてクエリの文字列が正確に一致している必要があります。返されたトークンを、キーワードのフィールドの値と一致するよう絞り込む指定ができます。query で演算子(フィールド)を指定しない場合、すべての登録トークンが検索結果に表示されることになります。
たとえば、
{URL}?query="device_type:CHROME_BROWSER+token_state:REVOKED
と指定した場合、次のような登録トークンが返されます。
{
"tokenId": "token_id_value",
"tokenPermanentId": "token_Permanent_id_value",
"kind": "admin#directory#chromeEnrollmentToken",
"orgUnitPath": "/Org-unit-path",
“tokenState”: “revoked”,
“creatorId”: “unique_id_of_user”,
"create_time": "2020-04-30T19:22:44Z",
"tokenType": "chromeBrowser",
}
特定のフィールドでフィルタして検索するには、次のフィールドを指定します。
フィールド | 説明 |
---|---|
device_type | 登録トークンが使用されるデバイスの種類です。現時点でサポートされているのは CHROME_BROWSER のみです。 |
token_state | 登録トークンのステータスです。サポートされている値は、REVOKED、ACTIVE、EXPIRED です。 |
登録トークンを作成する
組織部門で Chrome 登録トークンを作成するには、次の POST リクエストを使用し、「認証」セクションに従って取得したアクセス トークンを含めます。
注: このコードサンプルでは、読みやすくするために改行を挿入しています。
POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/
{my_customer|customerId}/chrome/enrollmentTokens
- customerId は、お客様の Google アカウントを表す一意の識別子です。
- アカウント管理者の代理としてリクエストを実行する場合は、ご自分のアカウントの customerId を表す文字列 my_customer を使用することもできます。また、ユーザー情報を取得する(Retrieve a user)操作によってcustomerId の値を取得することもできます。この操作のパスの userKey パラメータには、管理者のメールアドレスまたは管理者の一意のユーザー ID を使用します。
このリクエストで使用できるすべてのペイロード パラメータは以下のとおりです。
パラメータ | 必須 / 省略可 | 型 | 説明 |
---|---|---|---|
expire_time | 省略可 | string | 作成した登録トークンの有効期限です(「yyyy-MM-ddThh:mm:ssZ」形式)。このフィールドを指定しない場合、ユーザーが取り消すまで登録トークンは有効です。 |
org_unit_path | 省略可 | string | 登録トークンの作成対象となる組織部門です。このフィールドを指定しない場合、最上位の組織部門に対して登録トークンが作成されます。 |
token_type | 必須 | string | 登録トークンの作成対象となる Chrome デバイスの種類です。現地点でサポートされているのは「CHROME_BROWSER」のみです。 |
ttl | 省略可 | string | 作成した登録トークンの有効期間です。秒単位で指定し、末尾に「s」を付けます。たとえば、トークンを 1 時間有効にする場合、このフィールドを「3600s」に設定します。このフィールドを指定しない場合、登録トークンはユーザーが取り消すまで有効になります。 |
例
リクエストの例
POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/chrome/enrollmentTokens
{
"token_type": "CHROME_BROWSER",
"org_unit_path": "/org-unit-path",
"expire_time": "2021-04-30T19:22:44Z",
}
JSON レスポンス
リクエストが成功すると、200 番の HTTP ステータス コードが返されます。レスポンスでは、ステータス コードと一緒に Chrome 登録トークンのプロパティが返されます。
{
"tokenId": "token_id_value",
"tokenPermanentId": "token_Permanent_id_value",
"kind": "admin#directory#chromeEnrollmentToken",
"orgUnitPath": "/Org-unit-path",
"state": "active",
"creatorId”: "unique_id_of_user",
"create_time": "2020-04-30T19:22:44Z",
"expire_time": "2021-04-30T19:22:44Z",
"tokenType": "chromeBrowser",
}
登録トークンを取り消す
登録トークンを取り消すには、次の POST リクエストを使用し、「認証」セクションに従って取得したアクセス トークンを含めます。
注: このコードサンプルでは、読みやすくするために改行を挿入しています。
POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/
{my_customer|customerId}/chrome/enrollmentTokens/{tokenPermanentId}:revoke
- customerId は、お客様の Google アカウントを表す一意の識別子です。
- アカウント管理者の代理としてリクエストを実行する場合は、ご自分のアカウントの customerId を表す文字列 my_customer を使用することもできます。また、ユーザー情報を取得する(Retrieve a user)操作によってcustomerId の値を取得することもできます。この操作のパスの userKey パラメータには、管理者のメールアドレスまたは管理者の一意のユーザー ID を使用します。
- tokenPermanentId は登録トークンの一意の識別子であり、登録トークンの「List(一覧表示リクエスト)」または「Create(作成リクエスト)」のレスポンスに含まれる「tokenPermanentId」フィールドに表示されます。
例
リクエストの例
POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/chrome/enrollmentTokens/token_permanent_id_value:revoke
JSON レスポンス
リクエストが成功すると、200 番の HTTP ステータス コードが返されます。