Ämnen
Auktorisering
Innan du använder alla Chrome Browser Cloud Management-API:er måste du aktivera Admin SDK API (om det inte redan har aktiverats) i Google Developer Console genom att följa den här länken och välja det projekt som du vill aktivera. API:et.
Härifrån kan du få en token för åtkomst till API:
- Oauth2.0 med identitetsstöld med ett tjänstkonto (läs avsnittet Auktorisera med identitetsstöld) nedan
- 3-sidig Oauth2.0 utan identitetsstöld (Du kan auktorisera dina begäranden enligt Oauth2-riktlinjen)
Följande omfattningar krävs för att auktorisera din åtkomst till Chrome Browser Cloud Management API:
https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly
eller
https://www.googleapis.com/auth/admin.directory.device.chromebrowsers
Auktorisera med identitetsstöld
Om du vill att vi ska använda ett tjänstekonto för identitetsstöld måste du
- Skapa ett tjänstkonto och ha de nödvändiga tjänstkontonycklarna för detta tjänstkonto. Du kan följa det här för att skapa ett tjänstkonto och få nycklarna för tjänstkontot.
- Klient-id:t för det här tjänstkontot måste auktoriseras för de OAuth-omfattningar som anges ovan. Gör detta genom att öppna administratörskonsolen under Säkerhet -> API-kontroller -> Hantera domänomfattande delegering. Du lägger sedan till en ny klient. I den här dialogrutan motsvarar Klient-id det unika id:t för ditt tjänstkonto.
Med tjänstkontonycklarna måste du använda Googles API-klientbibliotek för det önskade språket för att begära en OAuth-åtkomsttoken för ditt tjänstkonto.
Dessutom måste OAuth-tokenbegäran utge sig för att vara en administratörsanvändare på din domän när du begär OAuth-token.
Här är ett exempel på hur du kan hämta kod med oauth-token med hjälp av Java API Client Libraries.
package takeout.api.credentials;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
public final class ApiRequestHelper {
public static String getAccessToken(
String serviceAccountKeyFilePath, String adminUserToImpersonate, Collection<String> scopes)
throws IOException {
InputStream is = new FileInputStream(serviceAccountKeyFilePath);
GoogleCredential credential =
GoogleCredential.fromStream(is).toBuilder()
.setServiceAccountScopes(scopes)
.setServiceAccountUser(adminUserToImpersonate)
.build();
if (!credential.refreshToken()) {
throw new RuntimeException(
String.format(
"Failed to fetch refresh token for service account defined in '%s' for user '%s' and"
+ " scopes '%s'",
serviceAccountKeyFilePath, adminUserToImpersonate, String.join(",", scopes)));
}
return credential.getAccessToken();
}
public static void printUsage() {
System.out.println(
"Usage: get_access_token <service account key file> <admin user> [<scope,scope>]");
}
public static void main(String[] args) throws Exception {
if (args.length < 2) {
printUsage();
return;
}
String scopes =
"https://www.googleapis.com/auth/admin.directory.device.chromebrowsers";
if (args.length >= 3) {
scopes = args[2];
}
System.out.println(
getAccessToken(args[0], args[1], new ArrayList<String>(Arrays.asList(scopes.split(",")))));
}
private ApiRequestHelper() {}
}
Med hjälp av den här exempelkoden kan du hämta en åtkomsttoken som du kan använda för att anropa API. Om nyckelfilen till exempel lagras i /home/private_key.json och det administratörskonto du vill använda för att göra begäran är admin@domän.com, kör du exekverfilen med följande argument:
ApiRequestHelper
/home/private_key.json admin@domän.com
Obs! Administratörens e-postadress som används är inte e-postadressen för servicekontot (som har formatet <project-name>-<id>@<projektnamn>.iam.gserviceaccount.com).
ChromeBrowser
Chrome-webbläsare som är registrerade i Chrome Browsers Cloud Management.
Resursrepresentation
Följande JSON-mall används för Chrome-webbläsarresurser i Directory API:
{
"kind": "admin#directory#browserdevice",
"deviceId": string,
"osPlatform": string,
"osPlatformVersion": string,
"osArchitecture":string,
"osVersion": string,
"machineName": string,
"annotatedLocation": string,
"annotatedUser": string,
"annotatedAssetId": string,
"annotatedNotes": string,
"lastPolicyFetchTime": dateTime,
"lastRegistrationTime": dateTime,
"lastActivityTime":dateTime,
"lastStatusReportTime":dateTime,
"virtualDeviceId": string,
"serialNumber": string,
"orgUnitPath": string,
"extensionCount":int,
"policyCount": int,
"safeBrowsingClickThroughCount": int,
"lastDeviceUser": string,
"browserVersions": [string],
"lastDeviceUsers":[
"userName": strin,
"lastStatusReportTime":dateTime,
]
"machinePolicies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
"browsers": [
"browserVersion": string,
"channel": string,
"lastStatusReportTime": dateTime,
"lastPolicyFetchTime": dateTime,
"executablePath": string,
"installedBrowserVersion": string,
"plugins":[
"name": string,
"description": string,
"fileame" string,
]
"profiles": [
"name": string,
"id": string,
"lastStatusReportTime": dateTime,
"lastPolicyFectchTime": dateTime,
"safeBrowsingWarnings": int,
"safeBrowsingWarningsClickThrough": int,
"chromeSignedinUserEmail": string,
"extensionPolicies": [
"extensionId": string,
"extensionName": string,
"policies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
]
"extensions": [
"extensionId": string,
"version": string,
"permissions": [string],
"name": string,
"description":string,
"appType": string,
"homepageUrl": string,
"installType": string,
"configuredAppPolicy": string,
"disabled": boolean,
"icons": [
"size": int,
"url": string,
]
]
"userPolicies": [
"source": string,
"name": string,
"value": string,
"error": string,
]
"safeBrowsingWarningsResetTime": string
]
}
Anropa API:et
Hämta alla Chrome-webbläsarenheter för ett konto
Begränsning: nextPageToken
som returneras av begäran har en timmes livslängd. Om din begäran har ett stort antal Chrome-enheter kan din sidtoken löpa ut innan du kan slutföra listan över alla enheter. I detta fall kanske du vill använda ett filter för din begäran så att det blir färre enheter som returneras av sökfrågan. Filtrering efter organisationsenhet är ofta ett bra sätt att minska antalet resultat.
Om du vill returnera en lista över alla Chrome-enheter som har tilldelats ett konto använder du följande GET-begäran och inkluderar auktoriseringen som beskrivs i Auktorisering. Kodexemplet innehåller radreturer för att det ska bli lättare att läsa.
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{min_kund|kund-id} /
devices/chromebrowsers?projection= {FULL|BAS}&query= {frågesträng}&orderBy= {orderBy
kategori}&sortOrder= {ASCENDING|DESCENDING}&sidtoken= {token för nästa resultatsida
om tillämpligt &maxResults=max antal resultat per sida}
- Kund-id är en unik identifierare för kundens Google-konto.
- När du utger dig för att vara kontoadministratör kan du även använda strängen my_customer som representerar kundens id för kontot. Ett annat sätt att få värdet för kund-id är att använda åtgärden Hämta en användare. Använd administratörens e-postadress eller ditt unika administratörs-id i åtgärdens userKey-parameter.
Följande är en referens till alla sökfrågeparametrar som kan användas i begäran:
Parameter | Typ | Beskrivning |
---|---|---|
maxResults | integer | Maximalt antal resultat att returnera. Standard- och maxvärdet är 100. |
orderBy | string | Egenskap för webbläsaren Chrome som ska användas för att sortera resultat. |
Godkända värden på är | ||
"id" – Id för enheten med webbläsaren Chrome installerad. | ||
"last_sync" – Datumet och tiden då Chrome-webbläsaren senast registrerades, senast synkroniserades med policyinställningar eller överförde en rapport. | ||
"machine_name" – Namnet på datorn som är kopplad till enheten. | ||
"extension_count" – det totala antalet tillägg som rapporterats i webbläsaren Chrome. | ||
"policy_count" – det totala antalet policyer för Chrome-enheter som rapporterats. | ||
"os_version" – OS för enheten som webbläsaren Chrome är installerad på. | ||
"last_signed_in_user" – Chrome-enhetens senast inloggade användare. | ||
"annotated_user" – användare av webbläsaren Chrome enligt kommentarer från administratören. | ||
"annotated_location" – Chrome-enhetens enhetsplats enligt administratörens kommentarer. | ||
"annotated_asset_id" – resurs-id för Chrome-webbläsaren som kommenterats av administratören. | ||
"notes" – anteckningar för Chrome-enheter som administratören har kommenterat. | ||
"browser_version_channel" – Den senaste versionen och kanalen av Chrome som rapporterats av enheten. | ||
"org_unit" – den organisationsenhet som enheten finns under. | ||
"enrollment_date" – Enhetens registreringsdatum. | ||
"save_browsing_clickthrough" – antal klick för Säker webbsökning som den här enheten har rapporterat. | ||
"platform_major_version" – OS-typ och huvudversion, t.ex.(Windows 10).: | ||
"last_activity" – när aktiviteten på enheten gjordes senast: | ||
"browser_version_sortable" – Den äldsta webbläsarversionen som är installerad på enheten.: | ||
"os_version_sortable" – OS-typ och fullständig version.: | ||
orgUnitPath | string | Organisationsenhetens fullständiga sökväg eller unika id. |
groupId | string | Det fullständiga resursnamnet för gruppen i formen grupper/{group} eller dess unika id. |
pageToken | string | Sökparametern pageToken används för att begära nästa sida med sökresultat. Sökparametern pageTokens uppföljningsbegäran är nästaPageToken från ditt tidigare svar. |
projektion | string | Begränsa information som returneras till en uppsättning valda fält. |
Godkända värden är: | ||
"BASIC" – inkluderar enbart de grundläggande metadatafälten (dvs. de som finns i kolumnerna på administratörskonsolens webbläsarlista enligt uppräkningen ovan) | ||
"FULL" – Inkluderar alla metadatafält (enligt uppräkningen ovan) | ||
sökfråga | string | Söksträng med listsidans frågespråk som beskrivs i avsnittet nedan (Filtrera sökfrågespråk). |
sortOrder | string | Om resultaten ska visas i stigande eller fallande ordning. Måste användas med parametern orderBy. |
Godkända värden är: | ||
"ASCENDING" – stigande ordning. | ||
"DESCENDING" – fallande ordning. |
Exempel: Filtrera enheter efter datornamn
I det första exemplet söker vi efter specifika datornamn med query=machine_name:CLIENT2012. Svaret innehåller en resurs för webbläsaren Chrome, där maskinnamnet är helpdesk:
JSON-begäran
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers?projection=BASIC&query=machine_name:CLIENT2012&orderBy=status
&sortOrder=ASCENDING&maxResults=100
JSON-svar
En lyckad begäran returnerar statuskoden HTTP 200. Här följer en lista över webbläsarenheter som matchar dina frågeparametrar:
{
"kind": "directory#browserdevices",
"browsers": [
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19505",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-04T00:29:17.484Z",
"lastActivityTime": "2019-11-04T00:29:17.484Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
},
],
"nextPageToken": "abcdefghijkl123"
}
Hämta en Chrome-webbläsarenhet
Om du vill hämta egenskaperna för en Chrome-webbläsare använder du följande GET-begäran och inkluderar auktoriseringen som beskrivs i Auktorisera begäranden. Kodexemplet innehåller radreturer för att det ska bli lättare att läsa.
GET
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/deviceId?projection={FULL|BASIC}
- Kund-id är en unik identifierare för kundens Google-konto.
- När du utger dig för att vara kontoadministratör kan du även använda strängen my_customer som representerar kundens id för kontot. Ett annat sätt att få värdet för kund-id är att använda åtgärden Hämta en användare. Använd administratörens e-postadress eller ditt unika administratörs-id i åtgärdens userKey-parameter.
- Detta enhets-id är en unik identifierare för en enhet och finns i svaret från funktionen Hämta alla Chrome-enheter. Information om frågesträngar, begäran och svarsegenskaper finns i API-referens.
Följande är en referens till alla sökfrågeparametrar som kan användas i begäran:
Parameter | Typ | Beskrivning |
---|---|---|
deviceId | string | Enhetens unika id. I svaret från metoden browsersdevices.list returneras deviceId.Obs! Den här parametern är obligatorisk. |
projektion | string | Avgör om svaret innehåller hela listan över egenskaper eller bara en delmängd. |
Godkända värden är: | ||
”BASIC”: Inkluderar endast de grundläggande metadatafälten (dvs. de som finns i kolumnerna på administratörskonsolens webbläsarlista enligt uppräkningen ovan) | ||
FULL: Inkluderar alla metadatafält (enligt uppräkningen ovan) |
Exempel
JSON-begäran
En exempelbegäran. Kodexemplet innehåller radreturer för att det ska bli lättare att läsa.
GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/deviceId?projection=basic
JSON-svar
En lyckad begäran returnerar statuskoden HTTP 200. Tillsammans med statuskoden returnerar svaret Chrome-enhetens egenskaper:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
"deviceIdentifiersHistory": {
"records": [
{
"identifiers": {
"machineName": "CLIENT2012",
"serialNumber": "ABCD1234567890" },
"firstRecordTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z"}
],
“has_device_id_collision”: “false”
}
}
Språk i filtersökfråga
När du använder parametern "query" i en listbegäran måste varje term i frågan matchas i en specifik webbläsare för att den ska vara giltig.Om du inte anger några operatorer (fält) i sökfrågan hittar webbläsaren en webbläsare med alla termer i alla, internt indexerade textfält. Om din fråga exempelvis är: "query=maskin 73", returnerar detta en webbläsare som har både termen "maskin" och "73" i alla fält som kan returneras i en webbläsarenhet som följande:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "machine_name",
"browser_versions": [
"73.0.0.0",
],
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
}
Tänk på följande – 1: Matchningen sker på ordgränser (alla skiljetecken eller blanksteg) så att du inte kan göra partiella matchningar på ord. I exemplet ovan skulle du inte kunna köra query='mask 73'.
Kommentar 2: Ordmatchning är inte skiftlägeskänslig så att en sökfråga med ”maskin” matchar både ”Maskin” och ”maskin”.
Du kan ange följande fält om du vill rikta in sökningen på specifika fält (Obs! Även om frågeorden inte är skiftlägeskänsliga är fältnamnen skiftlägeskänsliga).
Fält | Beskrivning |
---|---|
machine_name | Datornamn för webbläsaren Chrome. |
os_platform | OS-plattformen för enheten med webbläsaren Chrome. (t.ex. Windows) |
arch | CPU-arkitekturen för webbläsaren Chrome. (t.ex. x86_64) |
os_version | Operativsystemversionen för webbläsaren Chrome. (t.ex. 10.0.16299.904) |
plats | Den annoterade platsen för Chrome-enhet. |
användare | Användaren med kommentar för Chrome-enhet. |
asset_id | Id för annoterat tillgång för Chrome-enhet. |
note | Anteckningen för webbläsaren Chrome. |
register | Registreringstiden för Chrome-enhet. |
os | Kombinera OS-plattformen och huvudversionen av Chrome för Chrome-enheter (t.ex. Windows 10) |
browser_version | En rapporterad Chrome-webbläsare på Chrome-enheten (t.ex. 73) |
enrollment_token | Den registreringstoken som användes för att registrera Chrome-enhet. |
report | Den senaste rapporttiden för Chrome-webbläsaren |
synkronisera | Den senaste synkroniseringstiden för Chrome-webbläsaren. |
num_extensions | Antalet tillägg som rapporterats av Chrome-enhet. |
num_policies | Antalet policyer som rapporterats av webbläsaren Chrome. |
machine_user | Den senast rapporterade användaren av webbläsaren Chrome. |
last_activity | Senaste gången Chrome-enheten visade aktivitet (policyhämtning eller rapportering). |
has_device_id_collision | Enhets-id delas av flera datorer som Chrome identifierar som samma dator. Värden som stöds är true och false . |
För fält där tid kan anges (register, report, sync, last_activity) är tidsformatet ÅÅÅÅ-MM-DDThh:mm:ss (t.ex. 2020-01-01T12:00:00). Du kan även ange öppna eller stängda intervall för tiden:
Formulär |
Betydelse |
Exempel |
datetime |
Exakt på det angivna datumet eller den angivna tiden |
2011-03-23 2011-04-26T14:23:05 |
datetime..datetime |
Inom det angivna datum- eller tidsintervallet |
2011-03-23..2011-04-26 |
datetime.. |
På eller efter datumet eller tiden |
2011-04-26T14:23:05.. |
datetime.. |
På eller före datumet eller tiden |
..2011-04-26T14:23:05 |
Exempel på filterfrågor
Kommentar 1 Alla angivna exempel använder parametern query
i begäran. Parametervärdet måste vara korrekt kodat i webbadressen (dvs. för att undvika mellanslag med begäranden med flera villkor).
Kommentar 2: Alla frågor kan filtreras ytterligare till en viss organisationsenhet genom att du lägger till frågeparametern orgUnitPath
i begäran.
- Hitta alla enheter med datornamn som innehåller ett ord:
machine_name:LIX
- Hitta alla enheter med datornamn som innehåller ett ord som registrerats efter ett visst datum:
machine_name:LIX register:2011-04-26..
machine_name:LIX register:..2011-04-26
Frågor som för närvarande inte stöds:
- Hitta alla enheter där färre än ett visst antal tillägg har installerats (intervallfrågor för numeriska värden stöds inte).
- Hitta alla enheter som har ett datornamn som innehåller ett av två möjliga ord (med ELLER i sökfrågor).
Uppdatera en Chrome-enhet
Om du vill uppdatera de kommenterade fälten för Chrome-enheter som har tilldelats ett konto använder du följande PUT-begäran och inkluderar den åtkomsttoken som hämtas genom att följa avsnittet Auktorisering.
PUT
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/{deviceId}
- Kund-id är en unik identifierare för kundens Google-konto.
- När du utger dig för att vara kontoadministratör kan du även använda strängen my_customer som representerar kundens id för kontot. Ett annat sätt att få värdet för kund-id är att använda åtgärden Hämta en användare. Använd administratörens e-postadress eller ditt unika administratörs-id i åtgärdens userKey-parameter.
- Detta enhets-id är en unik identifierare för en enhet och finns i svaret från funktionen Hämta alla Chrome-enheter. Information om frågesträngar, begäran och svarsegenskaper finns i API-referens.
Följande parametrar kan användas i begäran:
Parameter | Obligatoriskt | Typ | Beskrivning |
---|---|---|---|
deviceId | krävs | string | Enhetens unika id. I svaret från metoden browsersdevices.list returneras deviceId.Obs! Den här parametern är obligatorisk. |
annotatedUser | valfritt | string | Den som använder enheten enligt administratörens kommentarer. |
annotatedLocation | valfritt | string |
Adress eller plats för enheten enligt administratörens notering |
annotatedNotes | valfritt | string | Kommentarer om enheten som har kommenterats av administratören |
annotatedAssetId | valfritt | string |
Resurs-id som administratören angett eller angett under registreringen. |
Exempel
JSON-begäran
En exempelbegäran. Kodexemplet innehåller radreturer för att det ska bli lättare att läsa.
PUT https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value
{
"deviceId": "device_id_value",
"annotatedUser": "user 1"
}
JSON-svar
En lyckad begäran returnerar statuskoden HTTP 200. Tillsammans med statuskoden returnerar svaret Chrome-enhetens egenskaper:
{
"deviceId": "device_id_value",
"kind": "admin#directory#browserdevice",
"osPlatform": "Windows",
"osVersion": "6.3.9600.19542",
"machineName": "CLIENT2012",
"lastRegistrationTime": "2019-11-27T12:55:27.230Z",
"lastActivityTime": "2019-11-27T12:55:27.230Z",
"virtualDeviceId": "virtual_device_id",
"orgUnitPath": "/Org-unit path",
"annotatedUser": "user 1"
}
Radera en Chrome-enhet
Om du vill ta bort en Chrome-webbläsarenhet som är tilldelad ett konto använder du följande DELETE-begäran och inkluderar den åtkomsttoken som hämtas genom att följa avsnittet Auktorisering.
DELETE
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices
chromebrowsers/{deviceId}
- Kund-id är en unik identifierare för kundens Google-konto.
- När du utger dig för att vara kontoadministratör kan du även använda strängen my_customer som representerar kundens id för kontot. Ett annat sätt att få värdet för kund-id är att använda åtgärden Hämta en användare. Använd administratörens e-postadress eller ditt unika administratörs-id i åtgärdens userKey-parameter.
- Detta enhets-id är en unik identifierare för en enhet och finns i svaret från åtgärden Hämta alla Chrome-enheter. Information om frågesträngar, begäran och svarsegenskaper finns i API-referens.
Exempel
En exempelbegäran:
DELETE https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value
JSON-svar
En lyckad begäran returnerar statuskoden HTTP 200.
Flytta en Chrome-enhet mellan organisationsenheter
Om du vill flytta Chrome-enheter som har tilldelats till ett konto från en organisationsenhet till en annan använder du följande POST-begäran och inkluderar den åtkomsttoken som hämtas genom att följa avsnittet Auktorisering.
POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices/chromebrowsers/moveChromeBrowsersToOu
- Kund-id är en unik identifierare för kundens Google-konto.
- När du utger dig för att vara kontoadministratör kan du även använda strängen my_customer som representerar kundens id för kontot. Ett annat sätt att få värdet för kund-id är att använda åtgärden Hämta en användare. Använd administratörens e-postadress eller ditt unika administratörs-id i åtgärdens userKey-parameter.
Följande parametrar kan användas i begäran:
Parameter | Typ | Beskrivning |
---|---|---|
resource_ids | Stränglista |
Lista över unika enhets-id:n för Chrome-webbläsarenheter som ska flyttas. Högst 600 webbläsare kan flyttas per begäran. |
org_unit_path | string |
Målorganisationsenhet att flytta enheter till. Fullständig sökväg till organisationsenheten eller dess id med prefixet ”id:" |
Exempel
En exempelbegäran.
POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/moveChromeBrowsersToOu
{
"org_unit_path": "/new-path",
"resource_ids": ["device_id_value_1","device_id_value_2"],
}
JSON-svar
En lyckad begäran returnerar statuskoden HTTP 200.