commit | f44c6eeb0aed1498d274cf6cf0f3fdca507dc847 | [log] [tgz] |
---|---|---|
author | Kevin Moore <kevmoo@users.noreply.github.com> | Thu Mar 21 09:30:20 2024 -0700 |
committer | GitHub <noreply@github.com> | Thu Mar 21 09:30:20 2024 -0700 |
tree | 442c0656a5ec090a1ad860001bb07b58a6ba5929 | |
parent | 22cea310e8e5978846585cda01e0a521151b9524 [diff] |
googleapis_auth: prepare v1.5.1 release (#608)
Package source | Description | Published Version |
---|---|---|
_discoveryapis_commons | Library for use by client APIs generated from Discovery Documents. | |
discoveryapis_generator | Create API Client libraries based on the Discovery API Service. | |
googleapis | Auto-generated client libraries for accessing Google APIs described through the API discovery service. | |
googleapis_beta | Auto-generated client libraries for accessing Google APIs described through the API discovery service. | |
googleapis_auth | Obtain Access credentials for Google services using OAuth 2.0 |
Google provides a large set of APIs that your applications can use to interact with Google products such as Google Drive, Gmail, Cloud Datastore, and Cloud Storage. These APIs are accessible via REST-like interfaces. The Dart team provides the googleapis and googleapis_beta packages, which provide generated Dart libraries for these APIs. Using the APIs, which are available for both web apps and cloud apps, is more convenient and less error-prone than using the raw REST protocol.
To use any of these APIs, you need a Cloud Project. In addition, based on the API being used, you need either an API key or a Client ID. And finally, depending on what kind of application is being used, you might need a Service Account. All these items are available through Google Developers Console when you create a project. Below are a few scenarios:
APIs require a Client ID specific to the kind of application when it accesses data that is owned by a user on behalf of that user (with consent): for example a browser application or a console application.
A server application can access data owned by the application itself by using a Service Account. Example: a server application accessing data in Datastore or Google Cloud Storage.
APIs that can be used to get public data require only an API key (for quota and billing purposes).
To set up authentication and authorization for your app, you need to create a project, create the authentication credentials, and activate the API you want to use, all of which you do at Google Developers Console.
Support for Google APIs is in two packages—googleapis and googleapis_beta. The googleapis package contains the APIs for all the APIs that are available in a stable version. The googleapis_beta package contains the APIs that are currently in beta and possibly only available through a Limited Preview program.
A third package, googleapis_auth, provides a way to obtain OAuth 2.0 credentials and an authenticated HTTP client required to use these APIs.
The rest of this document describes the following:
Here are just a few of the APIs your Dart programs can use.
You can see the full list of APIs at googleapis and googleapis_beta.
Applications sometimes require OAuth 2.0 for authentication and authorization. Whether an application needs OAuth 2.0 depends on the API being used and the kind of data being accessed. For example, an application needs OAuth 2.0 if it needs user consent. An application sometimes needs OAuth 2.0 depending on the following properties:
The OAuth 2.0 protocol provides different flows for different types of applications, including web server, installed, and client-side applications. For example, the following diagram illustrates the flow of communication for client-side applications:
To write a program that interacts with a Google product, you need several tools and packages.
Let‘s look at a web application example that uses the googleapis Google Drive API to retrieve documents from a user’s Google Drive. The following screenshot shows the app after it has retrieved a list of spreadsheets from a user's Google Drive and displayed them on the page.
You can find the source code for this example, drive_search_web, and others, at googleapis_examples on GitHub.
The section Example explained describes the code in the drive_search_web example related to googleapis and googleapis_auth. But first let's look at how to run the example.
To run this example, you need to create a project, activate an API, and create a Client ID in Google Developers Console. This section provides instructions about how to do these for this particular example. For complete information and detailed explanations, refer to Google Developers Console Help.
Go to Google Developers Console.
Click the Create Project button.
Provide a name for your project.
Click the Create button.
On left of the project page, click APIs & auth, click APIs.
Turn on the authentication for Drive API. It might take a couple of minutes to propagate.
On the left of the project page, under APIs & Auth, then click Credentials.
Click Create new Client ID.
In the popup window, click Web application, then fill in the form. Use http://localhost:8080 for Authorized JavaScript origins. Because this example is a client-side-only application, don‘t put a value in Authorized redirect URIs. This example runs on the local computer and uses port 8080. Ensure nothing else is using port 8080. If you later run this example from a different origin, you’ll need a new Client ID.
Click Create Client ID.
In the index.dart file, change to the client ID generated in the previous step. The client ID ends in apps.googeusercontent.com.
In the top directory of the application, run pub serve
.
Visit http://localhost:8080 in a browser window. After a little while, you'll see a built version of the app.
Click Authorize and accept the authorization on the page that appears.
Select a document type from the drop-down menu and click List. The program displays the list of files from the Google Drive of the user who is currently logged in. (Later the user can revoke access if desired.) Refer to Security - Account Settings for details.
This example, drive_search_web, uses the Google Drive API and the OAuth 2.0 API to access the user‘s files on Google Drive. Let’s look at the relevant parts of the example.
dependencies: googleapis_auth: '>=0.1.0 < 0.2.0' googleapis: '>=0.1.1 < 0.2.0'
import 'package:googleapis_auth/auth_browser.dart' as auth; import 'package:googleapis/drive/v2.dart' as drive;
final identifier = new auth.ClientId( "<custom-app-id>.apps.googleusercontent.com", null); final scopes = [drive.DriveApi.DriveScope];
authorizedClient(loginButton, identifier, scopes).then((client) { ... }
Let's take a look at authorizedClient().
Future authorizedClient(ButtonElement loginButton, auth.ClientId id, scopes) { return auth.createImplicitBrowserFlow(id, scopes) .then((auth.BrowserOAuth2Flow flow) { return flow.clientViaUserConsent(forceUserConsent: false).catchError((_) { loginButton.text = ''; return loginButton.onClick.first.then((_) { return flow.clientViaUserConsent(forceUserConsent: true); }); }, test: (error) => error is auth.UserConsentException); }); }
First the code initializes the browser flow as illustrated in the OAuth 2.0 diagram above. Then the program attempts to proceed without user consent using flow.clientViaUserConsent() with false as a parameter value. If the user previously gave consent, this will succeed. Otherwise, the program sets up the authorization button in the UI. When the user presses the button, the program brings up a popup window where the user can provide consent. To ask the user for consent, the code call flow.clientViaUserConsent() again using true for the parameter value.
var api = new drive.DriveApi(client);
Future<List<drive.File>> searchTextDocuments(drive.DriveApi api, int max, String query) { var docs = []; Future next(String token) { // The API call returns only a subset of the results. It is possible // to query through the whole result set via "paging". return api.files.list(q: query, pageToken: token, maxResults: max) .then((results) { docs.addAll(results.items); // If we would like to have more documents, we iterate. if (docs.length < max && results.nextPageToken != null) { return next(results.nextPageToken); } return docs; }); } return next(null); }
For APIs such as Cloud Datastore and Cloud Storage you need a Google service account, which is an account that represents your application instead of an individual end user. You can create one when creating a new Client ID: just click Service account instead of Web application.
The example cloudstorage_upload_download_service_account needs a service account because it uses the Google Cloud Storage API.
Let's take a quick look at the relevant code.
The following code creates account credentials from the service account specified in the details of the given JSON string. After you create the service account, you can download the JSON from the Cloud Console. Then enter the appropriate information to replace the placeholders.
final accountCredentials = new auth.ServiceAccountCredentials.fromJson(r''' { "private_key_id": "<please fill in>", "private_key": "<please fill in>", "client_email": "<please fill in>@developer.gserviceaccount.com", "client_id": "<please fill in>.apps.googleusercontent.com", "type": "service_account" } ''');
The program selects the scopes it will use and gets the StorageAPI, just like the previous example retrieved the Drive API.
final scopes = [storage.StorageApi.DevstorageFullControlScope]; ... var api = new storage.StorageApi(client);
Using the credentials and scopes parameters, a call to clientViaServiceAccount gets an authenticated client that can use the Storage APIs.
auth.clientViaServiceAccount(accountCredentials, scopes).then((client) { ... var regexp = new RegExp(r'^gs://([^/]+)/(.+)$'); switch (args.first) { case 'upload': ... }
Note that the code shown above creates accountCredentials, which identifies this application. The code specified by then() processes the command-line arguments and uploads or downloads a file as indicated.
The following line of code uses the Storage API to upload a media file to Google Cloud Storage.
return api.objects.insert(null, bucket, name: object, uploadMedia: media);
Here's a convenient list of the resources you might need:
The following notes for those who are contributing to this package. If you are only using this package, you can skip this section.
If you are only making changes to googleapis_auth
, then you only need to run tests for that package and can skip the remainder of this section. Specifically, before submitting a pull request:
$ pushd googleapis_auth $ pub get $ pub run test $ dart format . --fix $ popd
Otherwise...
Clone this package and run pub upgrade
from the generator
directory.
$ cd generator $ rm -rf .dart_tool $ pub upgrade
Download and generate the APIs using the config.yaml
configuration (avoid doing this on corp network, use cloudshell instead).
$ dart generator/bin/generate.dart run_config download
Note: You may need to reset some of the downloaded discovery documents, such as drive, or prediction.
Generate the APIs.
$ dart generator/bin/generate.dart run_config generate
Create a diff with the previous APIs to determine whether a minor or a major update to the version number is required.
Update the appropriate CHANGELOG.md
file under resources/
.
Update config.yaml
with a new version number and generate again.
$ dart generator/bin/generate.dart run_config generate
Run the tests.
$ pushd generated/googleapis $ pub get $ pub run test $ cd ../googleapis_beta $ pub get $ pub run test $ popd
Commit the downloaded discovery documents and generated packages.
If you ever need to ignore a specific API method or make a manual change to anything inside discovery/
, you should add the relevant diff to the overrides/
directory.
overrides/<desired-api>.json
file.git diff overrides/<desired-api>.json > overrides/<name>.diff
to create a diff file.Note: The name of the diff file is not important, but if possible, it is advised to associate the name with the relevant GitHub issue. For example, if your manual change is related to issue #123, then the diff file should be named i123.diff
.
Read the README and the code for the packages on pub.dev: googleapis_auth.
Check out additional APIs that are currently in beta and possibly only available through a Limited Preview program: googleapis_beta.
Play with some examples.
Read the reference documentation. These APIs are common to many languages including Python, Java, and others. You can refer to the general reference documentation at the developers' products page. Find the product you're interested in on that page and follow the link. Be sure to look the API reference docs for Dart as some of the Dart APIs have quirks.