Skip to content

Latest commit

 

History

History
 
 

gcloud-java-resourcemanager

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 

README.md

Google Cloud Java Client for Resource Manager (Alpha)

Java idiomatic client for [Google Cloud Resource Manager] (https://cloud.google.com/resource-manager/).

Build Status Coverage Status Maven Codacy Badge Dependency Status

Note: This client is a work-in-progress, and may occasionally make backwards-incompatible changes.

Quickstart

If you are using Maven, add this to your pom.xml file

<dependency>
  <groupId>com.google.gcloud</groupId>
  <artifactId>gcloud-java-resourcemanager</artifactId>
  <version>0.1.4</version>
</dependency>

If you are using Gradle, add this to your dependencies

compile 'com.google.gcloud:gcloud-java-resourcemanager:0.1.4'

If you are using SBT, add this to your dependencies

libraryDependencies += "com.google.gcloud" % "gcloud-java-resourcemanager" % "0.1.4"

Example Application

ResourceManagerExample is a simple command line interface for the Cloud Resource Manager. Read more about using the application on the ResourceManagerExample docs page.

Authentication

Unlike other gcloud-java service libraries, gcloud-java-resourcemanager only accepts Google Cloud SDK credentials at this time. If you are having trouble authenticating, it may be that you have other types of credentials that override your Google Cloud SDK credentials. See more about Google Cloud SDK credentials and credential precedence in the global README's Authentication section.

About Google Cloud Resource Manager

Google Cloud Resource Manager provides a programmatic way to manage your Google Cloud Platform projects. With this API, you can do the following:

  • Get a list of all projects associated with an account.
  • Create new projects.
  • Update existing projects.
  • Delete projects.
  • Undelete projects that you don't want to delete.

Google Cloud Resource Manager is currently in beta and may occasionally make backwards incompatible changes.

Be sure to activate the Google Cloud Resource Manager API on the Developer's Console to use Resource Manager from your project.

See the gcloud-java API Resource Manager documentation to learn how to interact with the Cloud Resource Manager using this client Library.

Getting Started

Prerequisites

You will need to set up the local development environment by installing the Google Cloud SDK and running the following command in command line: gcloud auth login.

Note: You don't need a project ID to use this service. If you have a project ID set in the Google Cloud SDK, you can unset it by typing gcloud config unset project in command line.

Installation and setup

You'll need to obtain the gcloud-java-resourcemanager library. See the Quickstart section to add gcloud-java-resourcemanager as a dependency in your code.

Creating an authorized service object

To make authenticated requests to Google Cloud Resource Manager, you must create a service object with Google Cloud SDK credentials. You can then make API calls by calling methods on the Resource Manager service object. The simplest way to authenticate is to use Application Default Credentials. These credentials are automatically inferred from your environment, so you only need the following code to create your service object:

import com.google.gcloud.resourcemanager.ResourceManager;
import com.google.gcloud.resourcemanager.ResourceManagerOptions;

ResourceManager resourceManager = ResourceManagerOptions.defaultInstance().service();

Getting a specific project

You can load a project if you know it's project ID and have read permissions to the project. To get a project, add the following import at the top of your file:

import com.google.gcloud.resourcemanager.Project;

Then use the following code to get the project:

String projectId = "my-globally-unique-project-id"; // Change to a unique project ID
Project project = resourceManager.get(projectId);

Creating a project

All you need to create a project is a globally unique project ID. You can also optionally attach a non-unique name and labels to your project. Read more about naming guidelines for project IDs, names, and labels here. To create a project, add the following imports at the top of your file:

import com.google.gcloud.resourcemanager.Project;
import com.google.gcloud.resourcemanager.ProjectInfo;

Then add the following code to create a project (be sure to change projectId to your own unique project ID).

String projectId = "my-globally-unique-project-id"; // Change to a unique project ID
Project project = resourceManager.create(ProjectInfo.builder(projectId).build());

Note that the return value from create is a Project that includes additional read-only information, like creation time, project number, and lifecycle state. Read more about these fields on the Projects page. Project, a subclass of ProjectInfo, adds a layer of service-related functionality over ProjectInfo.

Editing a project

To edit a project, create a new ProjectInfo object and pass it in to the Project.replace method. For example, to add a label to a project to denote that it's launch status is "in development", add the following code:

Project newProject = project.toBuilder()
    .addLabel("launch-status", "in-development")
    .build()
    .replace();

Note that the values of the project you pass in to replace overwrite the server's values for non-read-only fields, namely projectName and labels. For example, if you create a project with projectName "some-project-name" and subsequently call replace using a ProjectInfo object that didn't set the projectName, then the server will unset the project's name. The server ignores any attempted changes to the read-only fields projectNumber, lifecycleState, and createTime. The projectId cannot change.

Listing all projects

Suppose that we want a list of all projects for which we have read permissions. Add the following import:

import java.util.Iterator;

Then add the following code to print a list of projects you can view:

Iterator<Project> projectIterator = resourceManager.list().iterateAll();
System.out.println("Projects I can view:");
while (projectIterator.hasNext()) {
  System.out.println(projectIterator.next().projectId());
}

Complete source code

We put together all the code shown above into two programs. Both programs assume that you are running from your own desktop and used the Google Cloud SDK to authenticate yourself.

The first program creates a project if it does not exist. Complete source code can be found at GetOrCreateProject.java.

The second program updates a project if it exists and lists all projects the user has permission to view. Complete source code can be found at UpdateAndListProjects.java.

Java Versions

Java 7 or above is required for using this client.

Versioning

This library follows [Semantic Versioning] (http://semver.org/).

It is currently in major version zero (0.y.z), which means that anything may change at any time and the public API should not be considered stable.

Testing

This library has tools to help write tests for code that uses Resource Manager.

See TESTING to read more about testing.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information on how to get started.

License

Apache 2.0 - See LICENSE for more information.