Skip to content

Commit 4ec462e

Browse files
arnaud4dmouna-elmaazouzi
arnaud4d
and
mouna-elmaazouzi
authored
update main with google user info docs (#86)
* Feature/google userinfo (#1) * commands added - first draft * parameter tables updated * examples added * Update README.md * Table of contents updated * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * fixed broken tables --------- Co-authored-by: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com>
1 parent 3d4faad commit 4ec462e

File tree

1 file changed

+213
-0
lines changed

1 file changed

+213
-0
lines changed

‎README.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@
4646
- [Google.mail.untrash()](#googlemailuntrash)
4747
- [Google.mail.update()](#googlemailupdate)
4848
- [Google.mail.updateLabel()](#googlemailupdatelabel)
49+
- [Google.user.get()](#googleuserget)
50+
- [Google.user.getCurrent()](#googleusergetcurrent)
51+
- [Google.user.list()](#googleuserlist)
4952
- [labelInfo object](#labelinfo-object)
5053
- [Status object (Google Class)](#status-object-google-class)
5154

@@ -1030,6 +1033,7 @@ When you send an email with the "Microsoft" mail type, you must pass an object t
10301033
| toRecipients |[recipient](#recipient-object) collection | The To: recipients for the message. |
10311034

10321035
#### Attachment object
1036+
10331037
| Property | Type | Description |
10341038
|---|---|---|
10351039
|@odata.type|Text|always "#microsoft.graph.fileAttachment" (note that the property name requires that you use the `[""]` syntax)|
@@ -1050,19 +1054,22 @@ When you send an email with the "Microsoft" mail type, you must pass an object t
10501054
|contentType|Text| The type of the content. Possible values are `"text"` and `"html"` |No|
10511055

10521056
#### recipient object
1057+
10531058
| Property || Type | Description | Can be null of undefined |
10541059
|---|---|---|---|---|
10551060
|emailAddress||Object||Yes|
10561061
||address|Text|The email address of the person or entity.|No|
10571062
||name|Text| The display name of the person or entity.|Yes|
10581063

10591064
#### internetMessageHeader object
1065+
10601066
| Property | Type | Description | Can be null of undefined |
10611067
|---|---|---|---|
10621068
|name | Text|Represents the key in a key-value pair.|No|
10631069
|value|Text|The value in a key-value pair.|No|
10641070

10651071
#### followup flag object
1072+
10661073
| Property | Type | Description |
10671074
|---|---|---|
10681075
|dueDateTime|[dateTime &#124; TimeZone](#datetime-and-timezone)| The date and time that the follow up is to be finished. Note: To set the due date, you must also specify the `startDateTime`; otherwise, you will get a `400 Bad Request` response.|
@@ -1875,6 +1882,212 @@ To update a previously created label to 'Backup January':
18751882
$status:=$google.mail.updateLabel($labelId; {name:"Backup January"})
18761883
18771884
```
1885+
1886+
1887+
### Google.user.get()
1888+
1889+
**Google.user.get**( *id* : Text {; *select* : Text } ) : Object<br/>
1890+
**Google.user.get**( *id* : Text {; *select* : Collection } ) : Object
1891+
1892+
#### Parameters
1893+
1894+
|Parameter|Type||Description|
1895+
|---------|--- |:---:|------|
1896+
|id|Text|->|The *resourceName* of the person to provide information about. Use the *resourceName* field returned by [Google.user.list()](#googleuserlist) to specify the person.|
1897+
|select|Text \| Collection|->|Text: A comma-separated list of specific fields that you want to retrieve from each person (e.g., "names, phoneNumbers"). <br/>Collection: Collection of the specific fields.|
1898+
|Result|Object|<-|Represents user's details, like names, emails, and phone numbers based on the selected fields.|
1899+
1900+
#### Description
1901+
1902+
`Google.user.get()` provides information about a [user](https://developers.google.com/people/api/rest/v1/people#Person) based on the *resourceName* provided in `id` and fields optionally specified in `select`.
1903+
1904+
Supported fields include *addresses*, *ageRanges*, *biographies*, *birthdays*, *calendarUrls*, *clientData*, *coverPhotos*, *emailAddresses*, *events*, *externalIds*, *genders*, *imClients*, *interests*, *locales*, *locations*, *memberships*, *metadata*, *miscKeywords*, *names*, *nicknames*, *occupations*, *organizations*, *phoneNumbers*, *photos*, *relations*, *sipAddresses*, *skills*, *urls*, *userDefined*.
1905+
1906+
1907+
#### Returned object
1908+
1909+
The returned [user object](https://developers.google.com/people/api/rest/v1/people#Person) contains values for the specified field(s).
1910+
1911+
If no fields have been specified in `select`, `Google.user.get()` returns *emailAddresses* and *names*. Otherwise, it returns only the specified field(s).
1912+
1913+
#### Permissions
1914+
1915+
No authorization required to access public data. For private data, one of the following OAuth scopes is required:
1916+
1917+
https://www.googleapis.com/auth/contacts <br/>
1918+
https://www.googleapis.com/auth/contacts.readonly <br/>
1919+
https://www.googleapis.com/auth/contacts.other.readonly <br/>
1920+
https://www.googleapis.com/auth/directory.readonly <br/>
1921+
https://www.googleapis.com/auth/profile.agerange.read <br/>
1922+
https://www.googleapis.com/auth/profile.emails.read <br/>
1923+
https://www.googleapis.com/auth/profile.language.read <br/>
1924+
https://www.googleapis.com/auth/user.addresses.read <br/>
1925+
https://www.googleapis.com/auth/user.birthday.read <br/>
1926+
https://www.googleapis.com/auth/user.emails.read <br/>
1927+
https://www.googleapis.com/auth/user.gender.read <br/>
1928+
https://www.googleapis.com/auth/user.organization.read <br/>
1929+
https://www.googleapis.com/auth/user.phonenumbers.read <br/>
1930+
https://www.googleapis.com/auth/userinfo.email <br/>
1931+
https://www.googleapis.com/auth/userinfo.profile <br/>
1932+
https://www.googleapis.com/auth/profile.language.read
1933+
1934+
### Google.user.getCurrent()
1935+
1936+
**Google.user.getCurrent**( { *select* : Text } ) : Object<br/>
1937+
**Google.user.getCurrent**( { *select* : Collection } ) : Object
1938+
1939+
#### Parameters
1940+
1941+
|Parameter|Type||Description|
1942+
|---------|--- |:---:|------|
1943+
|select|Text \| Collection|->|Text: A comma-separated list of specific fields that you want to retrieve from each person (e.g., "names, phoneNumbers"). <br/>Collection: Collection of the specific fields.|
1944+
|Result|Object|<-|Represents user's details, like names, emails, and phone numbers based on the selected fields.|
1945+
1946+
#### Description
1947+
1948+
`Google.user.getCurrent()` provides information about the authenticated [user](https://developers.google.com/people/api/rest/v1/people#Person) based on fields specified in `select`.
1949+
1950+
Supported fields include *addresses*, *ageRanges*, *biographies*, *birthdays*, *calendarUrls*, *clientData*, *coverPhotos*, *emailAddresses*, *events*, *externalIds*, *genders*, *imClients*, *interests*, *locales*, *locations*, *memberships*, *metadata*, *miscKeywords*, *names*, *nicknames*, *occupations*, *organizations*, *phoneNumbers*, *photos*, *relations*, *sipAddresses*, *skills*, *urls*, *userDefined*.
1951+
1952+
#### Returned object
1953+
1954+
The returned [user object](https://developers.google.com/people/api/rest/v1/people#Person) contains values for the specific field(s).
1955+
1956+
If no fields have been specified in `select`, `Google.user.getCurrent()` returns *emailAddresses* and *names*. Otherwise, it returns only the specified field(s).
1957+
1958+
#### Permissions
1959+
1960+
Requires the same OAuth scope package as [Google.user.get()](#permissions-15).
1961+
1962+
#### Example
1963+
1964+
To retrieve information from the current user:
1965+
1966+
```4d
1967+
var $google : cs.NetKit.Google
1968+
var $oauth2 : cs.NetKit.OAuth2Provider
1969+
var $param : Object
1970+
1971+
// Set up parameters:
1972+
$param:={}
1973+
$param.name:="google"
1974+
$param.permission:="signedIn"
1975+
$param.clientId:="your-client-id" // Replace with your Google identity platform client ID
1976+
$param.clientSecret:="xxxxxxxxx"
1977+
$param.redirectURI:="http://127.0.0.1:50993/authorize/"
1978+
$param.scope:=[]
1979+
$param.scope.push("https://mail.google.com/")
1980+
1981+
$param.scope.push("https://www.googleapis.com/auth/contacts")
1982+
$param.scope.push("https://www.googleapis.com/auth/contacts.other.readonly")
1983+
$param.scope.push("https://www.googleapis.com/auth/contacts.readonly")
1984+
$param.scope.push("https://www.googleapis.com/auth/directory.readonly")
1985+
$param.scope.push("https://www.googleapis.com/auth/user.addresses.read")
1986+
$param.scope.push("https://www.googleapis.com/auth/user.birthday.read")
1987+
$param.scope.push("https://www.googleapis.com/auth/user.emails.read")
1988+
$param.scope.push("https://www.googleapis.com/auth/user.gender.read")
1989+
$param.scope.push("https://www.googleapis.com/auth/user.organization.read")
1990+
$param.scope.push("https://www.googleapis.com/auth/user.phonenumbers.read")
1991+
$param.scope.push("https://www.googleapis.com/auth/userinfo.email")
1992+
$param.scope.push("https://www.googleapis.com/auth/userinfo.profile")
1993+
1994+
1995+
$oauth2:=New OAuth2 provider($param)
1996+
1997+
$google:=cs.NetKit.Google.new($oauth2)
1998+
1999+
var $currentUser1:=$google.user.getCurrent()
2000+
//without parameters, returns by default "emailAddresses" and "names"
2001+
2002+
var $currentUser2:=$google.user.getCurrent("phoneNumbers")
2003+
//returns the field "phoneNumbers"
2004+
```
2005+
2006+
### Google.user.list()
2007+
2008+
**Google.user.list**( { *options* : Object } ) : Object
2009+
2010+
#### Parameters
2011+
2012+
|Parameter|Type||Description|
2013+
|---------|--- |:---:|------|
2014+
|options|Object|->|A set of options defining how to retrieve and filter user data|
2015+
|Result|Object|<-|An object containing a structured collection of [user](https://developers.google.com/people/api/rest/v1/people#Person) data organized into pages|
2016+
2017+
#### Description
2018+
2019+
`Google.user.list()` provides a list of domain profiles or domain contacts in the authenticated user's domain directory.
2020+
2021+
> If the contact sharing or the External Directory sharing is not allowed in the Google admin, the returned `users` collection is empty.
2022+
2023+
In *options*, you can pass the following properties:
2024+
2025+
|Property|Type|Description|
2026+
|---------|--- |------|
2027+
|select|Text \| Collection|Text: A comma-separated list of specific fields that you want to retrieve from each person (e.g., "names, phoneNumbers"). <br/>Collection: Collection of the specific fields. <br/>If omitted, defaults to returning emailAddresses and names.|
2028+
|sources|Text \| Collection|Specifies the directory source to return. Values: <br/>- DIRECTORY_SOURCE_TYPE_UNSPECIFIED (Unspecified), <br/>- DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT (Google Workspace domain shared contact), <br/>- DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE (default, Workspace domain profile).|
2029+
|mergeSources|Text \| Collection|Adds related data if linked by verified join keys such as email addresses or phone numbers. <br/>- DIRECTORY_MERGE_SOURCE_TYPE_UNSPECIFIED (Unspecified), <br/>- DIRECTORY_MERGE_SOURCE_TYPE_CONTACT (User owned contact).|
2030+
|top|Integer|Sets the maximum number of people to retrieve per page, between 1 and 1000 (default is 100).|
2031+
2032+
#### Returned object
2033+
2034+
The returned object holds a collection of [users objects](https://developers.google.com/people/api/rest/v1/people#Person) as well as [**status object**](status-object-google-class) properties and functions that allow you to navigate between different pages of results.
2035+
2036+
|Property|Type|Description|
2037+
|---------|--- |------|
2038+
|users|Collection|A collection of [user objects](https://developers.google.com/people/api/rest/v1/people#Person), each containing detailed information about individual users|
2039+
|isLastPage|Boolean|Indicates whether the current page is the last one in the collection of user data.|
2040+
|page|Integer|Represents the current page number of user information, starting from 1. By default, each page contains 100 results, but the page size limit can be adjusted using the *top* option.|
2041+
|next()|Function|A function that retrieves the next page of user information. Returns True if successful; otherwise, returns False if there is no next page and the users collection is not updated.|
2042+
|previous()|Function|A function that retrieves the previous page of user information. Returns True if successful; otherwise, returns False if there is no previous page and the users collection is not updated.|
2043+
|success|Boolean| [see Status object](#status-object-google-class)|
2044+
|statusText|Text| [see Status object](#status-object-google-class)|
2045+
|errors|Collection| [see Status object](#status-object-google-class)|
2046+
2047+
#### Permissions
2048+
2049+
Requires the same OAuth scope package as [Google.user.get()](#permissions-15).
2050+
2051+
#### Example
2052+
2053+
To retrieve user data in a structured collection organized into pages with a maximum of `top` users per page:
2054+
2055+
```4d
2056+
var $google : cs.NetKit.Google
2057+
var $oauth2 : cs.NetKit.OAuth2Provider
2058+
var $param : Object
2059+
2060+
$param:={}
2061+
$param.name:="google"
2062+
$param.permission:="signedIn"
2063+
$param.clientId:="your-client-id" // Replace with your Google identity platform client ID
2064+
$param.clientSecret:="xxxxxxxxx"
2065+
$param.redirectURI:="http://127.0.0.1:50993/authorize/"
2066+
$param.scope:=[]
2067+
$param.scope.push("https://mail.google.com/")
2068+
2069+
$param.scope.push("https://www.googleapis.com/auth/contacts")
2070+
$param.scope.push("https://www.googleapis.com/auth/contacts.other.readonly")
2071+
$param.scope.push("https://www.googleapis.com/auth/contacts.readonly")
2072+
$param.scope.push("https://www.googleapis.com/auth/directory.readonly")
2073+
$param.scope.push("https://www.googleapis.com/auth/user.addresses.read")
2074+
$param.scope.push("https://www.googleapis.com/auth/user.birthday.read")
2075+
$param.scope.push("https://www.googleapis.com/auth/user.emails.read")
2076+
$param.scope.push("https://www.googleapis.com/auth/user.gender.read")
2077+
$param.scope.push("https://www.googleapis.com/auth/user.organization.read")
2078+
$param.scope.push("https://www.googleapis.com/auth/user.phonenumbers.read")
2079+
$param.scope.push("https://www.googleapis.com/auth/userinfo.email")
2080+
$param.scope.push("https://www.googleapis.com/auth/userinfo.profile")
2081+
2082+
2083+
$oauth2:=New OAuth2 provider($param)
2084+
2085+
$google:=cs.NetKit.Google.new($oauth2)
2086+
2087+
var $userList:=$google.user.list({top:10})
2088+
```
2089+
2090+
18782091
### labelInfo object
18792092

18802093
Several Google.mail label management methods use a `labelInfo` object, containing the following properties:

0 commit comments

Comments
 (0)