From 2524343a945d0f1165e9e1886ceed9b5c8a1bad8 Mon Sep 17 00:00:00 2001 From: kapilraajP Date: Wed, 14 Jul 2021 14:28:28 +0530 Subject: [PATCH 1/4] Update documentations to new format and make client isolated --- README.md | 349 ++++--------------------------------------- gpeople/Module.md | 84 +++++++++++ gpeople/Package.md | 329 ++-------------------------------------- gpeople/endpoint.bal | 21 ++- gpeople/utils.bal | 2 +- 5 files changed, 143 insertions(+), 642 deletions(-) create mode 100644 gpeople/Module.md diff --git a/README.md b/README.md index 48011a4..f885fa1 100644 --- a/README.md +++ b/README.md @@ -1,341 +1,48 @@ +# 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; +[Google People API](https://developers.google.com/people) is a contact and contact group management service developed by Google. -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; +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. +- [`ballerinax/googleapis.people`](https://docs.central.ballerina.io/ballerinax/googleapis.people/latest) -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; +## Building from the source +### Setting up the prerequisites -contacts:Client googleContactClient = checkpanic new (googleContactConfig); +1. Download and install Java SE Development Kit (JDK) version 11 (from one of the following locations). -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()); - } + * [Oracle](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; + * [OpenJDK](https://adoptopenjdk.net/) -configurable string refreshToken = ?; -configurable string clientId = ?; -configurable string clientSecret = ?; + > **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK. -contacts:GoogleContactsConfiguration googleContactConfig = { - oauth2Config: { - clientId: clientId, - clientSecret: clientSecret, - refreshUrl: contacts:REFRESH_URL, - refreshToken: refreshToken - } -}; +2. Download and install [Ballerina Swan Lake Beta2](https://ballerina.io/). -contacts:Client googleContactClient = checkpanic new (googleContactConfig); +### Building the source +Execute the following commands to build from the source: -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 run the 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/Module.md b/gpeople/Module.md new file mode 100644 index 0000000..5c650d1 --- /dev/null +++ b/gpeople/Module.md @@ -0,0 +1,84 @@ +## Overview +Ballerina connector for Google People API is connecting the Google People API via Ballerina language easily. 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) V1.0 version. + +## Prerequisites +Before using this connector in your Ballerina application, complete the following: +* Create [Google Account](https://accounts.google.com/signup/v2/webcreateaccount?hl=en&flowName=GlifWebSignIn&flowEntry=SignUp) +* Obtaining tokens + + Follow [this link](https://developers.google.com/identity/protocols/oauth2) and obtain the client ID, client secret and refresh token. + +## Quickstart + +To use the Google People API connector in your Ballerina application, update the .bal file as follows: + +### Step 1: Import connector +First, import the ballerinax/googleapis.people module into the Ballerina project. +```ballerina +import ballerinax/googleapis.people as people; +``` +### Step 2: Create a new connector instance + +You can now enter the credentials in the Google People API client configuration and create 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. You can create a contact as follows with `createContact` method by passing a `Person` record and `FieldMask[]` as parameters. Successful creation returns the created contact as a `PersonResponse` and the error cases returns an `error` object. + + ```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. + +## Quick reference +The following code snippets shows how the connector operations can be used in different scenarios after initializing the client. +* Create a contact + ``` 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); + ``` + +* Get contact by resource name + ```ballerina + people:FieldMask[] getPersonFields = [NAME, PHONE_NUMBER, EMAIL_ADDRESS]; + people:PersonResponse getResponse = check googleContactClient->getPeople(, getPersonFields); + ``` + +* Create a contact group + ```ballerina + people:ContactGroup createContactGroup = check googleContactClient->createContactGroup("TestContactGroup"); + ``` + +**[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..4958b7b 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 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 Google People API service. -## Connector Overview +### Compatibility +| | Version | +|:------------------:|:------------------------:| +| Ballerina Language | 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 in [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); From 3c03b55af2fd32fc8e98d8fdca807fdb9038f203 Mon Sep 17 00:00:00 2001 From: kapilraajP Date: Thu, 5 Aug 2021 13:19:50 +0530 Subject: [PATCH 2/4] Update documentation in Readme.md with suggested format --- README.md | 12 ++++-------- gpeople/Package.md | 10 +++++----- 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index f885fa1..50ca970 100644 --- a/README.md +++ b/README.md @@ -8,18 +8,14 @@ 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. -- [`ballerinax/googleapis.people`](https://docs.central.ballerina.io/ballerinax/googleapis.people/latest) +- [`googleapis.people`](https://docs.central.ballerina.io/ballerinax/googleapis.people/latest) ## Building from the source ### Setting up the prerequisites -1. Download and install Java SE Development Kit (JDK) version 11 (from one of the following locations). +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). - * [Oracle](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) - - * [OpenJDK](https://adoptopenjdk.net/) - - > **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK. + > **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK. 2. Download and install [Ballerina Swan Lake Beta2](https://ballerina.io/). @@ -30,7 +26,7 @@ Execute the following commands to build from the source: ``` bal build -c ./gpeople ``` -* To run the without tests: +* To build the package without tests: ``` bal build -c --skip-tests ./gpeople ``` diff --git a/gpeople/Package.md b/gpeople/Package.md index 4958b7b..2a052f2 100644 --- a/gpeople/Package.md +++ b/gpeople/Package.md @@ -6,16 +6,16 @@ The `ballerinax/googleapis.people` is a [Ballerina](https://ballerina.io/) conne This package provides the capability to access Google People API service. ### Compatibility -| | Version | -|:------------------:|:------------------------:| -| Ballerina Language | Swan Lake Beta2 | -| Google People API | V1 | +| | Version | +|---------------------|-----------------| +| Ballerina Language | Swan Lake Beta2 | +| Google People API | V1 | ## Report issues 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) ## Useful links -- Discuss code changes of the Ballerina project in [ballerina-dev@googlegroups.com](mailto:ballerina-dev@googlegroups.com). +- 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 From 322513cbb57803d8e4fde4fb1965b5eef921082c Mon Sep 17 00:00:00 2001 From: kapilraajP Date: Thu, 5 Aug 2021 13:37:43 +0530 Subject: [PATCH 3/4] Update documentation in Module.md with suggested format --- gpeople/Module.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/gpeople/Module.md b/gpeople/Module.md index 5c650d1..bdab085 100644 --- a/gpeople/Module.md +++ b/gpeople/Module.md @@ -54,31 +54,4 @@ people:Client googleContactClient = check new (googleContactConfig); ``` 2. Use `bal run` command to compile and run the Ballerina program. -## Quick reference -The following code snippets shows how the connector operations can be used in different scenarios after initializing the client. -* Create a contact - ``` 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); - ``` - -* Get contact by resource name - ```ballerina - people:FieldMask[] getPersonFields = [NAME, PHONE_NUMBER, EMAIL_ADDRESS]; - people:PersonResponse getResponse = check googleContactClient->getPeople(, getPersonFields); - ``` - -* Create a contact group - ```ballerina - people:ContactGroup createContactGroup = check googleContactClient->createContactGroup("TestContactGroup"); - ``` - **[You can find more samples here](https://github.com/ballerina-platform/module-ballerinax-googleapis.people/tree/main/gpeople/samples)** From 29b2d91ab73f318ad0ab841a47fd9f85712fd50d Mon Sep 17 00:00:00 2001 From: kapilraajP Date: Fri, 6 Aug 2021 10:55:46 +0530 Subject: [PATCH 4/4] Update documentation with suggested doc review changes --- gpeople/Module.md | 16 +++++++--------- gpeople/Package.md | 12 ++++++------ 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/gpeople/Module.md b/gpeople/Module.md index bdab085..5008046 100644 --- a/gpeople/Module.md +++ b/gpeople/Module.md @@ -1,27 +1,25 @@ ## Overview -Ballerina connector for Google People API is connecting the Google People API via Ballerina language easily. It provides capability to perform operations related to contacts and contact groups in Google Contacts. +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) V1.0 version. +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 [Google Account](https://accounts.google.com/signup/v2/webcreateaccount?hl=en&flowName=GlifWebSignIn&flowEntry=SignUp) -* Obtaining tokens - - Follow [this link](https://developers.google.com/identity/protocols/oauth2) and obtain the client ID, client secret and refresh token. +* 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 -First, import the ballerinax/googleapis.people module into the Ballerina project. +Import the ballerinax/googleapis.people module into the Ballerina project. ```ballerina import ballerinax/googleapis.people as people; ``` ### Step 2: Create a new connector instance -You can now enter the credentials in the Google People API client configuration and create Google People API client by passing the configuration: +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 = { @@ -38,7 +36,7 @@ people:Client googleContactClient = check new (googleContactConfig); ### Step 3: Invoke connector operation -1. You can create a contact as follows with `createContact` method by passing a `Person` record and `FieldMask[]` as parameters. Successful creation returns the created contact as a `PersonResponse` and the error cases returns an `error` object. +1. Create a contact via the `createContact` method by passing a `Person` record and `FieldMask[]` as parameters. ```ballerina people:Person person = { diff --git a/gpeople/Package.md b/gpeople/Package.md index 2a052f2..f105f8d 100644 --- a/gpeople/Package.md +++ b/gpeople/Package.md @@ -1,15 +1,15 @@ -Connects to Google People API from Ballerina +Connects to [Google People API](https://developers.google.com/people/api/rest) from Ballerina. ## Package overview The `ballerinax/googleapis.people` is a [Ballerina](https://ballerina.io/) connector for Google People API. -This package provides the capability to access Google People API service. +This package provides the capability to access the Google People API service. ### Compatibility -| | Version | -|---------------------|-----------------| -| Ballerina Language | Swan Lake Beta2 | -| Google People API | V1 | +| | Version | +|---------------------|---------------------------| +| Ballerina Language | Ballerina Swan Lake Beta2 | +| Google People API | V1 | ## Report issues