gcloud 0.4.0+1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 89

Google Cloud Platform support package (gcloud)

The gcloud package provides a high level "idiomatic Dart" interface to some of the most widely used Google Cloud Platform services. Currently the following services are supported:

  • Cloud Datastore
  • Cloud Storage
  • Cloud Pub/Sub

The APIs in this package are all based on the generic generated APIs in the googleapis and googleapis_beta packages.

This means that the authentication model for using the APIs in this package uses the googleapis_auth package.

Note that this package is only intended for being used with the standalone VM in a server or command line application. Don't expect this package to work on the browser.

The code snippets below demonstrating the use of this package all assume that the following imports are present:

import 'dart:io';
import 'package:googleapis_auth/auth_io.dart' as auth;
import 'package:http/http.dart' as http;
import 'package:gcloud/db.dart';
import 'package:gcloud/storage.dart';
import 'package:gcloud/pubsub.dart';
import 'package:gcloud/service_scope.dart' as ss;
import 'package:gcloud/src/datastore_impl.dart' as datastore_impl;

Getting access to the APIs

The first step in using the APIs is to get an authenticated HTTP client and with that create API class instances for accessing the different APIs. The code below assumes that you have a Google Cloud Project called my-project with credentials for a service account from that project stored in the file my-project.json.

// Read the service account credentials from the file.
var jsonCredentials = new File('my-project.json').readAsStringSync();
var credentials = new auth.ServiceAccountCredentials.fromJson(jsonCredentials);

// Get an HTTP authenticated client using the service account credentials.
var scopes = []
    ..addAll(datastore_impl.DatastoreImpl.SCOPES)
    ..addAll(Storage.SCOPES)
    ..addAll(PubSub.SCOPES);
var client = await auth.clientViaServiceAccount(credentials, scopes);

// Instantiate objects to access Cloud Datastore, Cloud Storage
// and Cloud Pub/Sub APIs.
var db = new DatastoreDB(
    new datastore_impl.DatastoreImpl(client, 's~my-project'));
var storage = new Storage(client, 'my-project');
var pubsub = new PubSub(client, 'my-project');

All the APIs in this package supports the use of 'service scopes'. Service scopes are described in details below.

ss.fork(() {
  // register the services in the new service scope.
  registerDbService(db);
  registerStorageService(storage);
  registerPubSubService(pubsub);

  // Run application using these services.
});

The services registered with the service scope can now be reached from within all the code running in the same service scope using the below getters.

dbService.
storageService.
pubsubService.

This way it is not necessary to pass the service objects around in your code.

Use with App Engine

The gcloud package is also integrated in the Dart appengine package. This means the gcloud services are available both via the appengine context and service scopes. The authentication required to access the Google Cloud Platform services is handled automatically.

This means that getting to the App Engine Datastore can be through either the App Engine context

var db = context.services.db;

or just using the service scope registration.

var db = dbService;

Cloud Datastore

Google Cloud Datastore provide a NoSQL, schemaless database for storing non-relational data. See the product page https://cloud.google.com/datastore/ for more information.

The Cloud Datastore API provides a mapping of Dart objects to entities stored in the Datastore. The following example shows how to annotate a class to make it possible to store instances of it in the Datastore.

@db.Kind()
class Person extends db.Model {
  @db.StringProperty()
  String name;

  @db.IntProperty()
  int age;
}

The Kind annotation tell that instances of this class can be stored. The class must also inherit from Model. Now to store an object into the Datastore create an instance and use the commit function.

var person = new Person()
    ..name = ''
    ..age = 42;
await db.commit(inserts: [person]);

The function query is used to build a Query object which can be run to perform the query.

var persons = (await db.query(Person).run()).toList();

NOTE: This package include a lower level API provided through the class Datastore on top of which the DatastoreDB API is build. The main reason for this additional API level is to bridge the gap between the different APIs exposed inside App Engine and through the public REST API. We reserve the rights to modify and maybe even remove this additional layer at any time.

Cloud Storage

Google Cloud Storage provide a highly available object store (aka BLOB store). See the product page https://cloud.google.com/storage/ for more information.

In Cloud Storage the objects (BLOBs) are organized in buckets. Each bucket has a name in a global namespace. The following code creates a new bucket named my-bucket and writes the content of the file my-file.txt to the object named my-object.

var bucket = await storage.createBucket('my-bucket');
new File('my-file.txt').openRead().pipe(bucket.write('my-object'));

The following code will read back the object.

bucket.read('my-object').pipe(new File('my-file-copy.txt').openWrite());

Cloud Pub/Sub

Google Cloud Pub/Sub provides many-to-many, asynchronous messaging. See the product page https://cloud.google.com/pubsub/ for more information.

Cloud Pub/Sub uses two concepts for messaging. Topics are used if you want to send messages and subscriptions are used to subscribe to topics and receive the messages. This decouples the producer of a message from the consumer of a message.

The following code creates a topic and sends a simple test message:

var topic = await pubsub.createTopic('my-topic');
await topic.publishString('Hello, world!')

With the following code a subscription is created on the topic and a message is pulled using the subscription. A received message must be acknowledged when the consumer has processed it.

var subscription =
    await pubsub.createSubscription('my-subscription', 'my-topic');
var pullEvent = await subscription.pull();
print(pullEvent.message.asString);
await pullEvent.acknowledge();

It is also possible to receive messages using push events instead of pulling from the subscription. To do this the subscription should be configured as a push subscription with an HTTP endpoint.

await pubsub.createSubscription(
    'my-subscription',
    'my-topic',
    endpoint: Uri.parse('https://server.example.com/push'));

With this subscription all messages will be send to the URL provided in the endpoint argument. The server needs to acknowledge the reception of the message with a 200 OK reply.

Running tests

If you want to run the end-to-end tests, a Google Cloud project is required. When running these tests the following environment variables need to be set:

GCLOUD_E2E_TEST_PROJECT
GCLOUD_E2E_TEST_KEY

The value of the environment variable GCLOUD_E2E_TEST_PROJECT is the name of the Google Cloud project to use. The value of the environment variable GCLOUD_E2E_TEST_KEY is a Google Cloud Storage path (starting with gs://) to a JSON key file for a service account providing access to the Cloud Project.

0.4.0+1

  • Made a number of strong-mode improvements.

  • Updated dependency on googleapis and googleapis_beta.

0.4.0

  • Remove support for FilterRelation.In and "propertyname IN" for queries: This is not supported by the newer APIs and was originally part of fat-client libraries which performed multiple queries for each iten in the list.

  • Adds optional forComparision named argument to Property.encodeValue which will be set to true when encoding a value for comparison in queries.

  • Upgrade to newer versions of package:googleapis and package:googleapis_beta

0.3.0

  • Upgrade to use stable package:googleapis/datastore/v1.dart.

  • The internal [DatastoreImpl] class takes now a project name without the s~ prefix.

0.2.0+14

  • Fix analyzer warning.

0.2.0+13

  • Remove crypto dependency and upgrade dart dependency to >=1.13 since this dart version provides the Base64 codec.

0.2.0+11

  • Throw a [StateError] in case a query returned a kind for which there was no model registered.

0.2.0+10

  • Address analyzer warnings.

0.2.0+9

  • Support value transformation in db.query().filter().
  • Widen constraint on googleapis and googleapis_beta.

0.2.0+8

  • Widen constraint on googleapis and googleapis_beta.

0.2.0+4

  • Storage.read now honors offset and length arguments.

0.2.0+2

  • Widen constraint on googleapis/googleapis_beta

0.2.0+1

  • Fix broken import of package:googleapis/common/common.dart.

0.2.0

  • Add support for Cloud Pub/Sub.
  • Require Dart version 1.9.

0.1.4+2

  • Enforce fully populated entity keys in a number of places.

0.1.4+1

  • Deduce the query partition automatically from query ancestor key.

0.1.4

  • Added optional defaultPartition parameter to the constructor of DatastoreDB.

0.1.3+2

  • Widened googleapis/googleapis_beta constraints in pubspec.yaml.

0.1.3+1

  • Change the service scope keys keys to non-private symbols.

0.1.3

  • Widen package:googleapis dependency constraint in pubspec.yaml.
  • Bugfix in package:appengine/db.dart: Correctly handle ListProperties of length 1.

0.1.2

  • Introduced package:gcloud/service_scope.dart library.
  • Added global getters for getting gcloud services from the current service scope.
  • Added an package:gcloud/http.dart library using service scopes.

0.1.1

  • Increased version constraint on googleapis{,_auth,_beta}.

  • Removed unused imports.

0.1.0

  • First release.

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  gcloud: "^0.4.0+1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:gcloud/common.dart';

import 'package:gcloud/datastore.dart';

import 'package:gcloud/db.dart';

import 'package:gcloud/http.dart';

import 'package:gcloud/pubsub.dart';

import 'package:gcloud/service_scope.dart';

import 'package:gcloud/storage.dart';
        
Version Uploaded Documentation Archive
0.4.0+1 Oct 6, 2017 Go to the documentation of gcloud 0.4.0+1 Download gcloud 0.4.0+1 archive
0.4.0 Mar 6, 2017 Go to the documentation of gcloud 0.4.0 Download gcloud 0.4.0 archive
0.3.0 Aug 29, 2016 Go to the documentation of gcloud 0.3.0 Download gcloud 0.3.0 archive
0.2.0+14 Aug 18, 2016 Go to the documentation of gcloud 0.2.0+14 Download gcloud 0.2.0+14 archive
0.2.0+13 Jun 8, 2016 Go to the documentation of gcloud 0.2.0+13 Download gcloud 0.2.0+13 archive
0.2.0+12 Apr 11, 2016 Go to the documentation of gcloud 0.2.0+12 Download gcloud 0.2.0+12 archive
0.2.0+11 Mar 8, 2016 Go to the documentation of gcloud 0.2.0+11 Download gcloud 0.2.0+11 archive
0.2.0+9 Dec 14, 2015 Go to the documentation of gcloud 0.2.0+9 Download gcloud 0.2.0+9 archive
0.2.0+8 Sep 21, 2015 Go to the documentation of gcloud 0.2.0+8 Download gcloud 0.2.0+8 archive
0.2.0+7 Sep 9, 2015 Go to the documentation of gcloud 0.2.0+7 Download gcloud 0.2.0+7 archive

All 25 versions...

Analysis

We analyzed this package on Apr 23, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.49.0
  • pana: 0.10.6

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
80 / 100
Health:
Code health derived from static analysis. [more]
99 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
99 / 100
Overall score:
Weighted score of the above. [more]
89
Learn more about scoring.

Platforms

Detected platforms: web, other

Platform components identified in package: mirrors.

Suggestions

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 1 error 10 hints.

    Strong-mode analysis of lib/service_scope.dart failed with the following error:

    line: 130 col: 10
    The return type 'void' isn't a 'Object', as defined by the method 'registerScopeExitCallback'.

    Strong-mode analysis of lib/src/db/models.dart gave the following hint:

    line: 122 col: 2
    'proxy' is deprecated and shouldn't be used.

    Similar analysis of the following files failed:

    • lib/src/pubsub_impl.dart (hint)
    • lib/src/storage_impl.dart (hint)
  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use gcloud.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.13.0 <2.0.0
googleapis >=0.2.0 <0.45.0 0.44.0 0.50.1
googleapis_beta >=0.10.0 <0.40.0 0.39.2 0.45.1
http >=0.11.0 <0.12.0 0.11.3+16
Transitive dependencies
_discoveryapis_commons 0.1.6
async 2.0.6
charcode 1.1.1
collection 1.14.9
path 1.5.1
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
Dev dependencies
googleapis_auth >=0.2.3 <0.3.0
http_parser >=2.0.0 <4.0.0 3.1.1
mime >=0.9.0+3 <0.10.0
unittest >=0.11.0 <0.12.0