Repository files navigation

Idiomatic Ruby client libraries forGoogle Cloud Platform APIs.

• Homepage
• Reference documentation

This repository includes client libraries for Google Cloud Platform services,along with a selected set of Google services unrelated to the cloud platform.

Most directories each correspond to a client library RubyGem, including itscode, tests, gemspec, and documentation. Some client libraries also includehandwritten samples in thesamples directory, and/or autogenerated samplesin thesnippets directory.

Most client libraries in this repository are automatically generated by theGAPIC Generator. A smallnumber are written and maintained by hand. You can identify a generated clientlibrary by the presence of.OwlBot.yaml in the library directory. For themost part, do not try to edit generated libraries by hand, because changes willbe overwritten by the code generator.

A few directories include support files, including:

• .github includes configuration for GitHub Actions and bots that help tomaintain this repository.
• .kokoro includes configuration for internal Google processes that help tomaintain this repository.
• .toys includes scripts for running CI, releases, and maintenance tasks.
• acceptance andintegration include shared fixtures for acceptance tests.
• obsolete contains older libraries that are obsolete and no longermaintained.

Issues for client libraries hosted here can be filed in theissues tab. However,this is not an official support channel. If you have support questions, file asupport request through the normal Google support channels, or post questionson a forum such as StackOverflow.

Pull requests arewelcome. Please see the section below oncontributing.

Some maintenance tasks can be run in theactions tab byauthorized personnel.

These client library RubyGems each include classes and methods that can be usedto make authenticated calls to specific Google APIs. Some libraries alsoinclude additional convenience code implementing common client-side workflowsor best practices.

In general, you can expect to:

1. Activate access to the API by creating a project ontheGoogle Cloud Console, enablingbilling if necessary, and enabling the API.

2. Choose a library and install it, typically byadding it to yourbundle. For example, here is howyou might add a the Translation service client to your Gemfile:

   # Gemfile# ... previous libraries ...gem"google-cloud-translate","~> 3.2"

3. Instantiate a client object. This object represents an authenticatedconnection to the service. For example, here is how you might create aclient for the translation service:

   require"google/cloud/translate"translation_client=Google::Cloud::Translate.translation_service

   Depending on your environment and authentication needs, you might need toprovide credentials to the client object.

4. Make API calls by invoking methods on the client. For example, here is howyou might translate a phrase:

   result=translation_client.translate_textcontents:["Hello, world!"],mime_type:"text/plain",source_language_code:"en-US",target_language_code:"ja-JP",parent:"projects/my-project-name"putsresult.translations.first.translated_text# => "こんにちは世界！"

To access a Google Cloud API, you will generally need to activate it in thecloud console. This typically involves three steps:

1. If you have not created aGoogle Cloud Project, doso. Point your browser to theGoogle Cloud Console, sign up ifneeded, and create or choose a project. Make note of the project number(which is numeric) or project ID (which is usually three or more wordsseparated by hyphens). Many services will require you to pass thatinformation in when calling an API.

2. For most services, you will need to provide billing information. If this isyour first time using Google Cloud Platform, you may be eligible for a freetrial.

3. Enable the API you want to use. Click the "APIs & Services" tab in the leftnavigation, then click the "Enable APIs and Services" button near the top.Search for the API you want by name, and click "Enable". A few APIs may beenabled automatically for you, but most APIs need to be enabled explicitly.

Once you have a project set up and have enabled an API, you are ready to beginusing a client library to call the API.

This repository contains two types of API client RubyGems: themain libraryfor the API (e.g. thegoogle-cloud-translate gemfor the Translation service), and one ore moreversioned libraries fordifferent versions of the service (e.g.google-cloud-translate-v2 andgoogle-cloud-translate-v3 for versions 2 and 3of the service, respectively). Note that we're referring to different versionsof thebackend service, not of the client library gem.

In most cases, you should install themain library (the one without a serviceversion in the name). This library will provide all the required code for makingcalls to the API. It may also provide additional convenience code implementingcommon client-side workflows or best practices. Often the main library willbring in one or more versioned libraries as dependencies, and the client anddata type classes you will use may actually be defined in a versioned library,but installing the main library will ensure you have access to the best toolsand interfaces for interacting with the service.

Theversioned libraries are lower-level libraries that target a specificversion of the service. You may choose to intall a versioned library directly,instead of or in addition to the main library, to handle advanced use cases thatrequire lower level access.

Note: Many services may also provide client libraries with names beginning withgoogle-apis-. Those clients are developed in adifferent repository,and utilize an older client technology that lacks some of the performance andease of use benefits of the clients in the google-cloud-ruby repository. Theolder clients may cover some services for which a google-cloud-ruby client isnot yet available, but for services that are covered, we generally recommendthe clients in the google-cloud-ruby repository over the older ones.

Most client libraries have directories in this repository, or you can look upthe name of the client library to use in the documentation for the service youare using. Install this library as a RubyGem, or add it to your Gemfile.

Most API calls must be accompanied by authentication information proving thatthe caller has sufficient permissions to make the call.

These API client libraries provide several mechanisms for attaching credentialsto API calls.

• If your application runs on an Google Cloud Platform hosting environmentsuch as Google Compute Engine, Google Container Engine, Google App Engine,Google Cloud Run, or Google Cloud Functions, the environment will provide"ambient" credentials which client libraries will recognize and useautomatically. You can generally configure these credentials in the hostingenvironment, for example per-VM in Google Compute Engine.

• You can also provide your own service account credentials by including aservice account key file in your application's file system and setting theenvironment variableGOOGLE_APPLICATION_CREDENTIALS to the path to thatfile. Client libraries will read this environment variable if it is set.

• Finally, you can override credentials in code by setting thecredentialsfield in the client configuration. This can be set globally on the clientclass or provided when you construct a client object.

For more information, see the authentication documentation for theclient library you are using, or theCloud authentication documentation.

These libraries are currently supported on Ruby 2.6 through Ruby 3.1. Olderversions of Rubymay still work, but are unsupported and not recommended.

In general, Google provides official support for Ruby versions that are activelysupported by Ruby Core--that is, Ruby versions that are either in normalmaintenance or in security maintenance, and not end of life. Seehttps://www.ruby-lang.org/en/downloads/branches/ for details about the Rubysupport schedule.

The libraries in this repository followSemantic Versioning.

Libraries are released at one of two different support quality levels:

GA: Libraries defined at the GA (general availability) quality level,indicated by a gem version number greater than or equal to 1.0, are stable. Thecode surface will not change in backwards-incompatible ways unless absolutelynecessary (e.g. because of critical security issues), or unless accompanying asemver-major version update (such as version 1.x to 2.x.) Issues and requestsagainst GA libraries are addressed with the highest priority.

Preview: Libraries defined at a Preview quality level, indicated by a gemversion number less than 1.0, are expected to be mostly stable and we'reworking towards their release candidate. However, these libraries may getbackwards-incompatible updates from time to time. We will still address issuesand requests with a high priority.

Note that thegem version is distinct from theservice version. Some backendservices have mulitple versions, for example versionsv2andv3of the translation service. These are treated asseparate services and willhaveseparate versioned clients, e.g. thegoogle-cloud-translate-v2 andgoogle-cloud-translate-v3 gems. These gems will in turn have their own gemversions, tracking the development of the two services.

Contributions to this repository are welcome. However, please note that many ofthe clients in this repository are automatically generated. The Ruby files inthose clients will have a comment to that effect near the top; changes to thosefiles will not be accepted as they will simply be overwritten by the codegenerator. If in doubt, please open an issue and ask the maintainers. See theCONTRIBUTING document for more information on how toget started.

Please note that this project is released with a Contributor Code of Conduct.By participating in this project you agree to abide by its terms. SeeCode of Conduct for more information.

This library is licensed under Apache 2.0. Full license text isavailable inLICENSE.

Pleasereport bugs at the project on Github.

If you have questions about how to use the clients or APIs, ask onStack Overflow.