diff --git a/README.md b/README.md index 48011a4..50ca970 100644 --- a/README.md +++ b/README.md @@ -1,341 +1,44 @@ +# Ballerina Google People API Connector + [![Build](https://github.com/ballerina-platform/module-ballerinax-googleapis.people/workflows/CI/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-googleapis.people/actions?query=workflow%3ACI) [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerinax-googleapis.people.svg)](https://github.com/ballerina-platform/module-ballerinax-googleapis.people/commits/master) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -# Ballerina Google People Connector -Connects to Google People using Ballerina. - -# Introduction -## Google People -[Google People](https://developers.google.com/people) is a contact-management service developed by Google. It lets users to organize their schedule and share events with others. The Google People endpoint allows you to access the Google People API Version v1 through Ballerina. - -## Key Features of Google People -* Manage Contacts -* Manage Contact Groups - -## Connector Overview - -The Google People Ballerina Connector allows you to access the Google People API Version V1 through Ballerina. The connector can be used to implement some of the most common use cases of Google People. The connector provides the capability to programmatically manage contacts and contact groups, CRUD operations on contacts and contact groups operations through the connector endpoints. - -![image](docs/images/people_api_connector.png) - -# Prerequisites - -* Java 11 Installed - Java Development Kit (JDK) with version 11 is required. - -* Download the Ballerina [distribution](https://ballerinalang.org/downloads/) SLAlpha5 - Ballerina Swan Lake Alpha Version 5 is required. - -* Instantiate the connector by giving authentication details in the HTTP client config. The HTTP client config has built-in support for BasicAuth and OAuth 2.0. Google People uses OAuth 2.0 to authenticate and authorize requests. - * The Google People connector can be minimally instantiated in the HTTP client config using client ID, client secret, and refresh token. - * Client ID - * Client Secret - * Refresh Token - * Refresh URL - -## Compatibility - -| | Versions | -|:---------------------------:|:-------------------------------:| -| Ballerina Language | Swan Lake Alpha 5 | -| Google People API | V1 | - - -Instantiate the connector by giving authentication details in the HTTP client config. The HTTP client config has built-in support for OAuth 2.0. Google People uses OAuth 2.0 to authenticate and authorize requests. The Google People connector can be minimally instantiated in the HTTP client config using client ID, client secret, and refresh token. - -**Obtaining Tokens to Run the Sample** - -1. Visit [Google API Console](https://console.developers.google.com), click **Create Project**, and follow the wizard to create a new project. -2. Go to **Credentials -> OAuth consent screen**, enter a product name to be shown to users, and click **Save**. -3. On the **Credentials** tab, click **Create credentials** and select **OAuth client ID**. -4. Select an application type, enter a name for the application, and specify a redirect URI (enter https://developers.google.com/oauthplayground if you want to use -[OAuth 2.0 playground](https://developers.google.com/oauthplayground) to receive the authorization code and obtain the refresh token). -5. Click **Create**. Your client ID and client secret appear. -6. In a separate browser window or tab, visit [OAuth 2.0 playground](https://developers.google.com/oauthplayground), select the required Google People API scopes, and then click **Authorize APIs**. -7. When you receive your authorization code, click **Exchange authorization code for tokens** to obtain the refresh token. - -**Add project configurations file** - -Add the project configuration file by creating a `Config.toml` file under the root path of the project structure. -This file should have following configurations. Add the tokens obtained in the previous step to the `Config.toml` file. - -#### For client operations -``` -[ballerinax.googleapis.people] -clientId = " -clientSecret = "" -refreshToken = "" -refreshUrl = "" - -``` -# **Samples** - -### Create a Contact -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - // Create Person/Contact with given name - contacts:Person person = { - "emailAddresses": [], - "names": [{ - "familyName": "Hardy", - "givenName": "Jason", - "unstructuredName": "Jason Hardy" - }] - }; - contacts:FieldMask[] personFields = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse|error createContact = googleContactClient->createContact(person, personFields); - if (createContact is contacts:PersonResponse) { - log:printInfo("Person/Contacts Details: " + createContact.toString()); - log:printInfo(createContact.resourceName.toString()); - } else { - log:printError("Error: " + createContact.toString()); - } -} -``` -### Fetch a Contact -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; +[Google People API](https://developers.google.com/people) is a contact and contact group management service developed by Google. -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; +This connector provides operations for connecting and interacting with Google People API endpoints over the network. +For more information about configuration and operations, go to the module. +- [`googleapis.people`](https://docs.central.ballerina.io/ballerinax/googleapis.people/latest) -contacts:Client googleContactClient = checkpanic new (googleContactConfig); +## Building from the source +### Setting up the prerequisites -public function main() { - string contactResourceName = ""; - contacts:Person person = { - "emailAddresses": [], - "names": [{ - "familyName": "Hardy", - "givenName": "Jason", - "unstructuredName": "Jason Hardy" - }] - }; - contacts:FieldMask[] personFields = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse|error createContact = googleContactClient->createContact(person, personFields); - if (createContact is contacts:PersonResponse) { - contactResourceName = <@untainted>createContact.resourceName; - log:printInfo("Person/Contacts Details: " + createContact.toString()); - log:printInfo(createContact.resourceName.toString()); - } else { - log:printError("Error: " + createContact.toString()); - } +1. Download and install Java SE Development Kit (JDK) version 11. You can install either [OpenJDK](https://adoptopenjdk.net/) or [Oracle JDK](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html). - // Fetch information about Person/Contact - contacts:FieldMask[] getPersonFields = [NAME, PHONE_NUMBER, EMAIL_ADDRESS]; - contacts:PersonResponse|error getResponse = googleContactClient->getPeople(contactResourceName, getPersonFields); - if (getResponse is contacts:PersonResponse) { - log:printInfo("Person/Contacts Details: " + getResponse.toString()); - log:printInfo(getResponse.resourceName.toString()); - } else { - log:printError("Error: " + getResponse.toString()); - } -} -``` -### Search a Contact using a string value -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; + > **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK. -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; +2. Download and install [Ballerina Swan Lake Beta2](https://ballerina.io/). -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; +### Building the source +Execute the following commands to build from the source: -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - // Search a Person/Contact with a string - contacts:FieldMask[] readMasks = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse[]|error response = googleContactClient->searchContacts("Test"); - if (response is contacts:PersonResponse[]) { - log:printInfo("Person/Contacts Details: " + response.toString()); - } else { - log:printError("Error: " + response.toString()); - } -} -``` - -### Delete a Contact -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - - string contactResourceName = ""; - - contacts:Person person = { - "emailAddresses": [], - "names": [{ - "familyName": "Hardy", - "givenName": "Jason", - "unstructuredName": "Jason Hardy" - }] - }; - contacts:FieldMask[] personFields = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse|error createContact = googleContactClient->createContact(person, personFields); - if (createContact is contacts:PersonResponse) { - contactResourceName = <@untainted>createContact.resourceName; - log:printInfo("Person/Contacts Details: " + createContact.toString()); - log:printInfo(createContact.resourceName.toString()); - } else { - log:printError("Error: " + createContact.toString()); - } - - // Delete a contact - var deleteContact = googleContactClient->deleteContact(contactResourceName); - if (deleteContact is ()) { - log:printInfo("Deleted a Contact"); - } else { - log:printError(deleteContact.toString()); - } -} -``` - -### Create a Contact Group -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - // Create Contact Group with given name - var createContactGroup = googleContactClient->createContactGroup("TestContactGroup"); - if (createContactGroup is contacts:ContactGroup) { - log:printInfo("Contact Group Details: " + createContactGroup.toString()); - log:printInfo(createContactGroup.resourceName.toString()); - } else { - log:printError("Error: " + createContactGroup.toString()); - } -} -``` -### Fetch a Contact Group -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - string contactGroupResourceName = ""; - // Create Contact Group with given name - var createContactGroup = googleContactClient->createContactGroup("TestContactGroup"); - if (createContactGroup is contacts:ContactGroup) { - log:printInfo("Contact Group Details: " + createContactGroup.toString()); - contactGroupResourceName = createContactGroup.resourceName; - log:printInfo(createContactGroup.resourceName.toString()); - } else { - log:printError("Error: " + createContactGroup.toString()); - } - - // Fetch information about Contact Group - contacts:ContactGroup|error getResponse = googleContactClient->getContactGroup(contactGroupResourceName, 10); - if (getResponse is contacts:ContactGroup) { - log:printInfo("Contact Group Details: " + getResponse.toString()); - log:printInfo(getResponse.resourceName.toString()); - } else { - log:printError("Error: " + getResponse.toString()); - } -} -``` +* To build the package: + ``` + bal build -c ./gpeople + ``` +* To build the package without tests: + ``` + bal build -c --skip-tests ./gpeople + ``` ## Contributing to Ballerina - As an open source project, Ballerina welcomes contributions from the community. -For more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md). - -## Code of Conduct - -All the contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct). +For more information, see the [Contribution Guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md). -## Useful Links +## Code of conduct +All contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct). -* Discuss the code changes of the Ballerina project in [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com). +## Useful links +* Discuss about code changes of the Ballerina project via [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com). * Chat live with us via our [Slack channel](https://ballerina.io/community/slack/). * Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag. - - -## How you can contribute - -As an open source project, we welcome contributions from the community. Check the [issue tracker](https://github.com/ballerina-platform/module-ballerinax-googleapis.people/issues) for open issues that interest you. We look forward to receiving your contributions. diff --git a/gpeople/Dependencies.toml b/gpeople/Dependencies.toml index 0606292..0bf975d 100644 --- a/gpeople/Dependencies.toml +++ b/gpeople/Dependencies.toml @@ -1,26 +1,24 @@ [[dependency]] org = "ballerina" name = "log" -version = "1.1.0-beta.1" +version = "1.1.0-beta.2" [[dependency]] org = "ballerina" name = "os" -version = "0.8.0-beta.1" +version = "0.8.0-beta.2" [[dependency]] org = "ballerina" name = "url" -version = "1.1.0-beta.1" +version = "1.1.0-beta.2" [[dependency]] org = "ballerina" name = "http" -version = "1.1.0-beta.1" +version = "1.1.0-beta.2" [[dependency]] org = "ballerina" name = "io" -version = "0.6.0-beta.1" - - +version = "0.6.0-beta.2" diff --git a/gpeople/Module.md b/gpeople/Module.md new file mode 100644 index 0000000..5008046 --- /dev/null +++ b/gpeople/Module.md @@ -0,0 +1,55 @@ +## Overview +Ballerina connector for Google People API connects the Google People API via Ballerina language with ease. It provides capability to perform operations related to contacts and contact groups in Google Contacts. + +This module supports [Google People API](https://developers.google.com/people/api/rest) v1.0. + +## Prerequisites +Before using this connector in your Ballerina application, complete the following: +* Create a [Google account](https://accounts.google.com/signup/v2/webcreateaccount?hl=en&flowName=GlifWebSignIn&flowEntry=SignUp) +* Obtain tokens - Follow [this link](https://developers.google.com/identity/protocols/oauth2) + +## Quickstart + +To use the Google People API connector in your Ballerina application, update the .bal file as follows: + +### Step 1: Import connector +Import the ballerinax/googleapis.people module into the Ballerina project. +```ballerina +import ballerinax/googleapis.people as people; +``` +### Step 2: Create a new connector instance + +Enter the credentials in the Google People API client configuration, and create the Google People API client by passing the configuration. + +```ballerina +people:GoogleContactsConfiguration googleContactConfig = { + oauth2Config: { + clientId: "", + clientSecret: , + refreshUrl: people:REFRESH_URL, + refreshToken: + } +}; + +people:Client googleContactClient = check new (googleContactConfig); +``` + +### Step 3: Invoke connector operation + +1. Create a contact via the `createContact` method by passing a `Person` record and `FieldMask[]` as parameters. + + ```ballerina + people:Person person = { + emailAddresses: [], + names: [{ + familyName: "Hardy", + givenName: "Jason", + unstructuredName: "Jason Hardy" + }] + }; + people:FieldMask[] personFields = [people:NAME, people:PHONE_NUMBER, people:EMAIL_ADDRESS]; + people:PersonResponse createContact = check googleContactClient->createContact(person, personFields); + ``` +2. Use `bal run` command to compile and run the Ballerina program. + +**[You can find more samples here](https://github.com/ballerina-platform/module-ballerinax-googleapis.people/tree/main/gpeople/samples)** diff --git a/gpeople/Package.md b/gpeople/Package.md index 378ea93..f105f8d 100644 --- a/gpeople/Package.md +++ b/gpeople/Package.md @@ -1,320 +1,21 @@ -# Ballerina Google People Connector -Connects to Google People using Ballerina. +Connects to [Google People API](https://developers.google.com/people/api/rest) from Ballerina. -# Introduction -## Google People -[Google People](https://developers.google.com/people) is a contact-management service developed by Google. It lets users to organize their schedule and share events with others. The Google People endpoint allows you to access the Google People API Version v1 through Ballerina. +## Package overview +The `ballerinax/googleapis.people` is a [Ballerina](https://ballerina.io/) connector for Google People API. -## Key Features of Google People -* Manage Contacts -* Manage Contact Groups +This package provides the capability to access the Google People API service. -## Connector Overview +### Compatibility +| | Version | +|---------------------|---------------------------| +| Ballerina Language | Ballerina Swan Lake Beta2 | +| Google People API | V1 | -The Google People Ballerina Connector allows you to access the Google People API Version V1 through Ballerina. The connector can be used to implement some of the most common use cases of Google People. The connector provides the capability to programmatically manage contacts and contact groups, CRUD operations on contacts and contact groups operations through the connector endpoints and listener for the events created in the contacts. +## Report issues -# Prerequisites +To report bugs, request new features, start new discussions, view project boards, etc., go to the [Ballerina Google People API repository](https://github.com/ballerina-platform/module-ballerinax-googleapis.people) -* Java 11 Installed - Java Development Kit (JDK) with version 11 is required. - -* Download the Ballerina [distribution](https://ballerinalang.org/downloads/) SLAlpha5 - Ballerina Swan Lake Alpha Version 5 is required. - -* Instantiate the connector by giving authentication details in the HTTP client config. The HTTP client config has built-in support for BasicAuth and OAuth 2.0. Google People uses OAuth 2.0 to authenticate and authorize requests. - * The Google People connector can be minimally instantiated in the HTTP client config using client ID, client secret, and refresh token. - * Client ID - * Client Secret - * Refresh Token - * Refresh URL - * In order to use listener address, resource id and channel id are additionally required. Address URL is url path of the listener. Channel id and resource id will be provided when channel is registered using watch operation. - * Address URL - * Resource ID - * Channel ID - -## Compatibility - -| | Versions | -|:---------------------------:|:-------------------------------:| -| Ballerina Language | Swan Lake Alpha 5 | -| Google People API | V1 | - - -Instantiate the connector by giving authentication details in the HTTP client config. The HTTP client config has built-in support for OAuth 2.0. Google People uses OAuth 2.0 to authenticate and authorize requests. The Google People connector can be minimally instantiated in the HTTP client config using client ID, client secret, and refresh token. - -**Obtaining Tokens to Run the Sample** - -1. Visit [Google API Console](https://console.developers.google.com), click **Create Project**, and follow the wizard to create a new project. -2. Go to **Credentials -> OAuth consent screen**, enter a product name to be shown to users, and click **Save**. -3. On the **Credentials** tab, click **Create credentials** and select **OAuth client ID**. -4. Select an application type, enter a name for the application, and specify a redirect URI (enter https://developers.google.com/oauthplayground if you want to use -[OAuth 2.0 playground](https://developers.google.com/oauthplayground) to receive the authorization code and obtain the refresh token). -5. Click **Create**. Your client ID and client secret appear. -6. In a separate browser window or tab, visit [OAuth 2.0 playground](https://developers.google.com/oauthplayground), select the required Google People API scopes, and then click **Authorize APIs**. -7. When you receive your authorization code, click **Exchange authorization code for tokens** to obtain the refresh token. - -**Add project configurations file** - -Add the project configuration file by creating a `Config.toml` file under the root path of the project structure. -This file should have following configurations. Add the tokens obtained in the previous step to the `Config.toml` file. - -#### For client operations -``` -[ballerinax.googleapis.people] -clientId = " -clientSecret = "" -refreshToken = "" -refreshUrl = "" - -``` -``` -# **Samples** - -### Create a Contact -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - // Create Person/Contact with given name - contacts:Person person = { - "emailAddresses": [], - "names": [{ - "familyName": "Hardy", - "givenName": "Jason", - "unstructuredName": "Jason Hardy" - }] - }; - contacts:FieldMask[] personFields = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse|error createContact = googleContactClient->createContact(person, personFields); - if (createContact is contacts:PersonResponse) { - log:printInfo("Person/Contacts Details: " + createContact.toString()); - log:printInfo(createContact.resourceName.toString()); - } else { - log:printError("Error: " + createContact.toString()); - } -} -``` -### Fetch a Contact -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - string contactResourceName = ""; - contacts:Person person = { - "emailAddresses": [], - "names": [{ - "familyName": "Hardy", - "givenName": "Jason", - "unstructuredName": "Jason Hardy" - }] - }; - contacts:FieldMask[] personFields = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse|error createContact = googleContactClient->createContact(person, personFields); - if (createContact is contacts:PersonResponse) { - contactResourceName = <@untainted>createContact.resourceName; - log:printInfo("Person/Contacts Details: " + createContact.toString()); - log:printInfo(createContact.resourceName.toString()); - } else { - log:printError("Error: " + createContact.toString()); - } - - // Fetch information about Person/Contact - contacts:FieldMask[] getPersonFields = [NAME, PHONE_NUMBER, EMAIL_ADDRESS]; - contacts:PersonResponse|error getResponse = googleContactClient->getPeople(contactResourceName, getPersonFields); - if (getResponse is contacts:PersonResponse) { - log:printInfo("Person/Contacts Details: " + getResponse.toString()); - log:printInfo(getResponse.resourceName.toString()); - } else { - log:printError("Error: " + getResponse.toString()); - } -} -``` -### Search a Contact using a string value -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - // Search a Person/Contact with a string - contacts:FieldMask[] readMasks = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse[]|error response = googleContactClient->searchContacts("Test"); - if (response is contacts:PersonResponse[]) { - log:printInfo("Person/Contacts Details: " + response.toString()); - } else { - log:printError("Error: " + response.toString()); - } -} -``` - -### Delete a Contact -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - - string contactResourceName = ""; - - contacts:Person person = { - "emailAddresses": [], - "names": [{ - "familyName": "Hardy", - "givenName": "Jason", - "unstructuredName": "Jason Hardy" - }] - }; - contacts:FieldMask[] personFields = [contacts:NAME, contacts:PHONE_NUMBER, contacts:EMAIL_ADDRESS]; - contacts:PersonResponse|error createContact = googleContactClient->createContact(person, personFields); - if (createContact is contacts:PersonResponse) { - contactResourceName = <@untainted>createContact.resourceName; - log:printInfo("Person/Contacts Details: " + createContact.toString()); - log:printInfo(createContact.resourceName.toString()); - } else { - log:printError("Error: " + createContact.toString()); - } - - // Delete a contact - var deleteContact = googleContactClient->deleteContact(contactResourceName); - if (deleteContact is ()) { - log:printInfo("Deleted a Contact"); - } else { - log:printError(deleteContact.toString()); - } -} -``` - -### Create a Contact Group -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - // Create Contact Group with given name - var createContactGroup = googleContactClient->createContactGroup("TestContactGroup"); - if (createContactGroup is contacts:ContactGroup) { - log:printInfo("Contact Group Details: " + createContactGroup.toString()); - log:printInfo(createContactGroup.resourceName.toString()); - } else { - log:printError("Error: " + createContactGroup.toString()); - } -} -``` -### Fetch a Contact Group -```ballerina -import ballerinax/googleapis.people as contacts; -import ballerina/log; - -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; - -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; - -contacts:Client googleContactClient = checkpanic new (googleContactConfig); - -public function main() { - string contactGroupResourceName = ""; - // Create Contact Group with given name - var createContactGroup = googleContactClient->createContactGroup("TestContactGroup"); - if (createContactGroup is contacts:ContactGroup) { - log:printInfo("Contact Group Details: " + createContactGroup.toString()); - contactGroupResourceName = createContactGroup.resourceName; - log:printInfo(createContactGroup.resourceName.toString()); - } else { - log:printError("Error: " + createContactGroup.toString()); - } - - // Fetch information about Contact Group - contacts:ContactGroup|error getResponse = googleContactClient->getContactGroup(contactGroupResourceName, 10); - if (getResponse is contacts:ContactGroup) { - log:printInfo("Contact Group Details: " + getResponse.toString()); - log:printInfo(getResponse.resourceName.toString()); - } else { - log:printError("Error: " + getResponse.toString()); - } -} -``` +## Useful links +- Discuss code changes of the Ballerina project via [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com). +- Chat live with us via our [Slack channel](https://ballerina.io/community/slack/). +- Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag diff --git a/gpeople/endpoint.bal b/gpeople/endpoint.bal index cac16d9..f76d8fd 100644 --- a/gpeople/endpoint.bal +++ b/gpeople/endpoint.bal @@ -16,22 +16,31 @@ import ballerina/http; -# Object for Google Contacts configuration. +# Object for Google People API configuration. # # + oauth2Config - OAuth client configuration # + secureSocketConfig - HTTP client configuration public type GoogleContactsConfiguration record { - http:BearerTokenConfig | http:OAuth2RefreshTokenGrantConfig oauth2Config; + http:BearerTokenConfig|http:OAuth2RefreshTokenGrantConfig oauth2Config; http:ClientSecureSocket secureSocketConfig?; }; -# Google Contacts Client. +# Ballerina Google People API connector provides the capability to access Google People API. +# This connector lets you to read and manage the authenticated user's contacts and contact groups. # -# + googleContactClient - The HTTP Client +# + googleContactClient - Connector HTTP endpoint @display {label: "Google People API", iconPath: "GooglePeopleLogo.png"} -public client class Client { - public http:Client googleContactClient; +public isolated client class Client { + final http:Client googleContactClient; + # Initializes the connector. During initialization you can pass either http:BearerTokenConfig + # if you have a bearer token or http:OAuth2RefreshTokenGrantConfig if you have Oauth tokens. + # Create a [Google account](https://accounts.google.com/signup/v2/webcreateaccount?utm_source=ga-ob-search&utm_medium=google-account&flowName=GlifWebSignIn&flowEntry=SignUp) and + # obtain tokens following [this guide](https://developers.google.com/identity/protocols/oauth2). + # Configure the OAuth2 tokens to have the [required permissions](https://developers.google.com/sheets/api/guides/authorizing). + # + # + googleContactConfig - Configuration for the connector + # + return - `http:Error` in case of failure to initialize or `null` if successfully initialized public isolated function init(GoogleContactsConfiguration googleContactConfig) returns error? { http:ClientSecureSocket? socketConfig = googleContactConfig?.secureSocketConfig; self.googleContactClient = check new (BASE_URL, { diff --git a/gpeople/utils.bal b/gpeople/utils.bal index 88717ee..d28f91c 100644 --- a/gpeople/utils.bal +++ b/gpeople/utils.bal @@ -185,7 +185,7 @@ isolated function convertImageToBase64String(string imagePath) returns @tainted # + pathProvided -Provided path # + options - Record that contains options parameters # + return - PersonResponse stream on success, else an error -function getContacts(http:Client googleContactClient, @tainted PersonResponse[] persons, string pathProvided = EMPTY_STRING, +isolated function getContacts(http:Client googleContactClient, @tainted PersonResponse[] persons, string pathProvided = EMPTY_STRING, ContactListOptions? options = ()) returns @tainted stream|ContactsTriggerResponse|error { string path = <@untainted>prepareUrlWithContactOptions(pathProvided, options); http:Response|error httpResponse = googleContactClient->get(path); diff --git a/gradle.properties b/gradle.properties index 38aaf24..4b7df88 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,4 +1,4 @@ org.gradle.caching=true group=org.ballerinalang.googleapis.people version=0.1.2-SNAPSHOT -ballerinaLangVersion=2.0.0-beta.1-20210511-182300-9317c52a \ No newline at end of file +ballerinaLangVersion=2.0.0-beta.2-20210621-194000-70c97122