googleapis-raw

These are raw bindings for Google APIs based on grpcio.

Version notes

This library is currently locked to grpcio 0.13.0 and protobuf 2.28.0. This is due to an internal dependency of grpcio. Be sure that you match these library versions in your library or application.

Documentation

To generate and open documentation, run:

cargo doc --open

Examples

To run hand-written examples, try:

cargo run --example spanner-query
cargo run --example bigtable-query

Setting up Google Cloud SDK

Before running examples, make sure the Google Cloud SDK is set up in your environment. If you need help, follow these guides:

1. Installing the SDK
2. Setting up the SDK
3. Getting started with Authentication

As a final check:

• Run gcloud info to see the SDK configuration.
• Run echo $GOOGLE_APPLICATION_CREDENTIALS to verify that the credentials have been set up.
• Run gcloud auth login to login into Google Cloud

There is Docker setup available that installs all necessary tools, libraries, see the README inside the ./docker folder.

Useful links for setting up specific Google services:

• Setting up Spanner
• Installing the Cloud SDK for Cloud Bigtable
• Quickstart using the Pub/Sub CLI tool

Generating Rust bindings from .proto files

NOTE: You may need to update these bindings after protobuf updates. The process requires an update to the protobuf-codegen cargo plugin.

This requires the installation of protobuf library and protoc-gen-rust, a plugin for protobuf. The installed protobuf version and the protobuf crate should have the same version, e.g. 2.7.0. Installation of the protoc-gen-rust plugin is done via cargo:

cargo install protobuf-codegen

Make sure the protoc-gen-rust binary is available in your $PATH env variable.

Then:

1. In the ./src directory, remove all the *.rs that are not mod.rs [1]. You may wish to run the prepare.sh script.

2. Run the ./generate.sh script

ensure that a proper build works by running cargo build.

[1] The generate.sh script will NOT generate the required mod.rs files for the directories. In addition, the generated rust modules will look for several modules that are super to their package. protoc may not overwrite an existing, generated rust file which could lead to complications. It's easiest if you simily leave the mod.rs files in place and remove the other rust files, or copy the mod.rs files from a backup. Running a cargo build will definitely identify the modules that may be missing and that you'll have to add via a line like:

pub(crate) use crate::{
    empty,
    iam::v1::{iam_policy, policy},
    longrunning::operations,
};

(which was taken from src/rpc/spanner/admin/instance/v1/mod.rs)

Please note that the source grpc repo may contiain one or more older submodule references that may need to be updated (e.g. .grpc/third_party/googleapis). This may require manual updating as well as manunal updating/correction of the various, mod.rs files. Pay close attention to interdependencies. These may need to be specified in the directory mods (see .src/storage/v1/mod.rs for an example. Remember, you can use the r# prefix in rust to except a reserved name for use, e.g. use mod crate::r#type)

Monitoring for changes

Google will introduce changes and modifications to the GRPC interface for spanner, bigtable and other service. You are STRONGLY encouraged to monitor the project release notes (particularly for Spanner and BigTable, as well as any other service this library should start to support). RSS feeds are available for these release notes, and are listed on their respective pages.

When Updating

When initializing the submodule dependencies, you can use

git submodule update --init --recursive

to do a targeted update of the grpc code:

git submodule update --remote grpc
pushd grpc/third_party
git submodule update --remote protobuf
git submodule update --remote googleapis
popd

to pull a version of the libraries you require. Unfortunately, I have found that git submodule update does NOT always properly update dependencies to the latest master/main version. Be sure that the grpc/third_party/googleapis submodule is updated at least once per quarter. This directory contains the Protobuf declarations and can often contain undisclosed changes that need to be reflected into the generated code.

NOTE: this may alter the pre-generated mod files requiring old modules to be dropped or new modules to be added. Ensure that the various mod.rs files capture these changes.

Google Cloud Console

Links to Google Cloud Console for our testing environment:

• Spanner Console
• Bigtable Console
• Pub/Sub Console

References

Google APIs and their .proto files:

• Spanner
• Bigtable
• Pub/Sub

Golang clients:

• Spanner client (docs)
• Bigtable client (docs)
• Pub/Sub client (docs)