google-cloud-resource_manager 0.39.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.yardopts +5 -9
- data/AUTHENTICATION.md +81 -141
- data/LICENSE.md +201 -0
- data/MIGRATING.md +194 -0
- data/README.md +131 -0
- data/lib/google/cloud/resource_manager/version.rb +6 -2
- data/lib/google/cloud/resource_manager.rb +546 -84
- data/lib/google-cloud-resource_manager.rb +5 -120
- metadata +14 -49
- data/CHANGELOG.md +0 -175
- data/CODE_OF_CONDUCT.md +0 -40
- data/CONTRIBUTING.md +0 -189
- data/LICENSE +0 -201
- data/LOGGING.md +0 -27
- data/OVERVIEW.md +0 -188
- data/TROUBLESHOOTING.md +0 -31
- data/lib/google/cloud/resource_manager/credentials.rb +0 -53
- data/lib/google/cloud/resource_manager/manager.rb +0 -300
- data/lib/google/cloud/resource_manager/policy.rb +0 -191
- data/lib/google/cloud/resource_manager/project/list.rb +0 -166
- data/lib/google/cloud/resource_manager/project/updater.rb +0 -151
- data/lib/google/cloud/resource_manager/project.rb +0 -502
- data/lib/google/cloud/resource_manager/resource.rb +0 -119
- data/lib/google/cloud/resource_manager/service.rb +0 -139
data/MIGRATING.md
ADDED
@@ -0,0 +1,194 @@
|
|
1
|
+
## Migrating to google-cloud-resource_manager 1.0
|
2
|
+
|
3
|
+
The 1.0 release of the google-cloud-resource_manager client is a significant
|
4
|
+
upgrade to add a number of new features in version V3 of the resource manager
|
5
|
+
service, and to bring the client interfaces and technology up to date with the
|
6
|
+
rest of Google's modern API clients. As part of this processs, substantial
|
7
|
+
interface changes were made, so existing code written for earlier versions of
|
8
|
+
this library will likely require updates to use this version. This document
|
9
|
+
describes the changes that have been made, and what you need to do to update
|
10
|
+
your usage.
|
11
|
+
|
12
|
+
To summarize:
|
13
|
+
|
14
|
+
* The client has been rewritten to use the new high-performance gRPC endpoint
|
15
|
+
for the new version V3 of the service. (Earlier client versions used the
|
16
|
+
HTTP/REST endpoint for version V1 of the service.)
|
17
|
+
* The library has been broken out into two libraries. The new gem
|
18
|
+
`google-cloud-resource_manager-v3` contains the actual client classes for
|
19
|
+
version V3 of the Resource Manager service, and the gem
|
20
|
+
`google-cloud-resource_manager` now simply provides a convenience wrapper.
|
21
|
+
See [Library Structure](#library-structure) for more info.
|
22
|
+
* The library uses a new configuration mechanism giving you closer control
|
23
|
+
over endpoint address, network timeouts, and retry. See
|
24
|
+
[Client Configuration](#client-configuration) for more info. Furthermore,
|
25
|
+
when creating a client object, you can customize its configuration in a
|
26
|
+
block rather than passing arguments to the constructor. See
|
27
|
+
[Creating Clients](#creating-clients) for more info.
|
28
|
+
* Previously, positional arguments were used to indicate required arguments.
|
29
|
+
Now, all method arguments are keyword arguments, with documentation that
|
30
|
+
specifies whether they are required or optional. Additionally, you can pass
|
31
|
+
a proto request object instead of separate arguments. See
|
32
|
+
[Passing Arguments](#passing-arguments) for more info.
|
33
|
+
* Nearly all classes have been redesigned and have different names. See
|
34
|
+
[Class Design](#class-design) for more info.
|
35
|
+
|
36
|
+
### Library Structure
|
37
|
+
|
38
|
+
Older 0.x releases of the `google-cloud-resource_manager` gem provided the
|
39
|
+
entire client interface in one gem. This included major data types, and client
|
40
|
+
objects with methods for the various calls. These classes were in turn powered
|
41
|
+
by the `google-apis-cloudresourcemanager_v1` gem which handled lower-level REST
|
42
|
+
calls.
|
43
|
+
|
44
|
+
With the 1.0 release, the `google-cloud-resource_manager` gem itself provides
|
45
|
+
factory methods for obtaining client objects, but the client classes and data
|
46
|
+
types themselves are defined in a separate gem
|
47
|
+
`google-cloud-resource_manager-v3`. Normally, your app can continue to install
|
48
|
+
`google-cloud-resource_manager`, which will bring in the lower-level
|
49
|
+
`google-cloud-resource_manager-v3` gem as a dependency. It is also possible for
|
50
|
+
to install only `google-cloud-resource_manager-v3` if you know you will use
|
51
|
+
only V3 of the service.
|
52
|
+
|
53
|
+
### Client Configuration
|
54
|
+
|
55
|
+
In older releases, if you wanted to customize performance parameters or
|
56
|
+
low-level behavior of the client (such as credentials, timeouts, or
|
57
|
+
instrumentation), you would pass a variety of keyword arguments to the client
|
58
|
+
constructor. It was also extremely difficult to customize the default settings.
|
59
|
+
|
60
|
+
With the 1.0 release, a configuration interface provides control over these
|
61
|
+
parameters, including defaults for all instances of a client, and settings for
|
62
|
+
each specific client instance. For example, to set default credentials and
|
63
|
+
timeout for all Resource Manager V3 projects clients:
|
64
|
+
|
65
|
+
```
|
66
|
+
Google::Cloud::ResourceManager::V3::Projects::Client.configure do |config|
|
67
|
+
config.credentials = "/path/to/credentials.json"
|
68
|
+
config.timeout = 10.0
|
69
|
+
end
|
70
|
+
```
|
71
|
+
|
72
|
+
Individual RPCs can also be configured independently. For example, to set the
|
73
|
+
timeout for the `list_projects` call:
|
74
|
+
|
75
|
+
```
|
76
|
+
Google::Cloud::ResourceManager::V3::Projects::Client.configure do |config|
|
77
|
+
config.rpcs.list_projects.timeout = 20.0
|
78
|
+
end
|
79
|
+
```
|
80
|
+
|
81
|
+
Defaults for certain configurations can be set for all ResourceManager versions
|
82
|
+
globally:
|
83
|
+
|
84
|
+
```
|
85
|
+
Google::Cloud::ResourceManager.configure do |config|
|
86
|
+
config.credentials = "/path/to/credentials.json"
|
87
|
+
config.timeout = 10.0
|
88
|
+
end
|
89
|
+
```
|
90
|
+
|
91
|
+
Finally, you can override the configuration for each client instance. See the
|
92
|
+
next section on [Creating Clients](#creating-clients) for details.
|
93
|
+
|
94
|
+
### Creating Clients
|
95
|
+
|
96
|
+
In older releases, to create a client object, you would use the
|
97
|
+
`Google::Cloud::ResourceManager.new` class method. Keyword arguments were
|
98
|
+
available to configure parameters such as credentials and timeouts.
|
99
|
+
|
100
|
+
With the 1.0 release, use named class methods of
|
101
|
+
`Google::Cloud::ResourceManager` to create a client object. For example, use
|
102
|
+
`Google::Cloud::ResourceManager.projects` to create a client for
|
103
|
+
projects-related RPCs. You may select a service version using the `:version`
|
104
|
+
keyword argument. However, other configuration parameters should be set in a
|
105
|
+
configuration block when you create the client.
|
106
|
+
|
107
|
+
Old:
|
108
|
+
```
|
109
|
+
client = Google::Cloud::ResourceManager.new credentials: "/path/to/credentials.json"
|
110
|
+
```
|
111
|
+
|
112
|
+
New:
|
113
|
+
```
|
114
|
+
client = Google::Cloud::ResourceManager.projects do |config|
|
115
|
+
config.credentials = "/path/to/credentials.json"
|
116
|
+
end
|
117
|
+
```
|
118
|
+
|
119
|
+
The configuration block is optional. If you do not provide it, or you do not
|
120
|
+
set some configuration parameters, then the default configuration is used. See
|
121
|
+
[Client Configuration](#client-configuration).
|
122
|
+
|
123
|
+
### Passing Arguments
|
124
|
+
|
125
|
+
In older releases, required arguments would be passed as positional method
|
126
|
+
arguments, while most optional arguments would be passed as keyword arguments.
|
127
|
+
|
128
|
+
With the 1.0 release, all RPC arguments are passed as keyword arguments,
|
129
|
+
regardless of whether they are required or optional. Additionally, the
|
130
|
+
structure of some arguments may have changed: many arguments that were
|
131
|
+
previously "flattened" are now provided in the form of data structures, usually
|
132
|
+
the same data structures returned as responses. For example:
|
133
|
+
|
134
|
+
Old:
|
135
|
+
```
|
136
|
+
client = Google::Cloud::ResourceManager.new
|
137
|
+
|
138
|
+
# The project ID is a positional argument by itself, and optional arguments
|
139
|
+
# are separate keyword arguments.
|
140
|
+
response = client.create_project "my-project", name: "My great project"
|
141
|
+
```
|
142
|
+
|
143
|
+
New:
|
144
|
+
```
|
145
|
+
client = Google::Cloud::ResourceManager.projects
|
146
|
+
|
147
|
+
# Create a project data structure and pass it as a keyword argument.
|
148
|
+
project = {
|
149
|
+
project_id: "my-project",
|
150
|
+
name: "My great project"
|
151
|
+
}
|
152
|
+
|
153
|
+
response = client.create_project project: project
|
154
|
+
```
|
155
|
+
|
156
|
+
Additionally, in older releases, it was often difficult or impossible to
|
157
|
+
provide per-call options such as timeouts. In the 1.0 release, you can now
|
158
|
+
pass call options using a _second set_ of keyword arguments.
|
159
|
+
|
160
|
+
New:
|
161
|
+
```
|
162
|
+
client = Google::Cloud::ResourceManager.projects
|
163
|
+
|
164
|
+
project = {
|
165
|
+
project_id: "my-project",
|
166
|
+
name: "My great project"
|
167
|
+
}
|
168
|
+
|
169
|
+
# Use a hash to wrap the normal call arguments, and
|
170
|
+
# then add further keyword arguments for the call options.
|
171
|
+
response = client.create_project({ project: project }, timeout: 10.0)
|
172
|
+
```
|
173
|
+
|
174
|
+
### Class Design
|
175
|
+
|
176
|
+
In older releases, the main client object was of type
|
177
|
+
`Google::Cloud::ResourceManager::Project`, and included methods covering all
|
178
|
+
functionality for version V1 of the Resource Manager. In the 1.0 release,
|
179
|
+
several different client objects are provided, covering the various parts of
|
180
|
+
the expanded Resource Manager V3 functionality. These client classes include
|
181
|
+
`Google::Cloud::ResourceManager::V3::Projects::Client`,
|
182
|
+
`Google::Cloud::ResourceManager::V3::Projects::Organizations`,
|
183
|
+
`Google::Cloud::ResourceManager::V3::Projects::Folders`, and others. You can
|
184
|
+
construct instances of these classes using the provided class methods on the
|
185
|
+
`Google::Cloud::ResourceManager` module.
|
186
|
+
|
187
|
+
In older releases, certain data types were represented by Ruby classes under
|
188
|
+
the `Google::Cloud::ResourceManager` namespace, including
|
189
|
+
`Google::Cloud::ResourceMnaager::Policy` and
|
190
|
+
`Google::Cloud::ResourceManager::Resource`. The functionality in these data
|
191
|
+
types was extremely limited. In the 1.0 release, you will use protocol buffer
|
192
|
+
message types for all resources, such as
|
193
|
+
`Google::Cloud::ResourceManager::V3::Project` and
|
194
|
+
`Google::Cloud::ResourceManager::V3::Organization`.
|
data/README.md
ADDED
@@ -0,0 +1,131 @@
|
|
1
|
+
# Ruby Client for the Cloud Resource Manager API
|
2
|
+
|
3
|
+
Creates, reads, and updates metadata for Google Cloud Platform resource containers.
|
4
|
+
|
5
|
+
Creates, reads, and updates metadata for Google Cloud Platform resource containers.
|
6
|
+
|
7
|
+
Actual client classes for the various versions of this API are defined in
|
8
|
+
_versioned_ client gems, with names of the form `google-cloud-resource_manager-v*`.
|
9
|
+
The gem `google-cloud-resource_manager` is the main client library that brings the
|
10
|
+
verisoned gems in as dependencies, and provides high-level methods for
|
11
|
+
constructing clients. More information on versioned clients can be found below
|
12
|
+
in the section titled *Which client should I use?*.
|
13
|
+
|
14
|
+
View the [Client Library Documentation](https://cloud.google.com/ruby/docs/reference/google-cloud-resource_manager/latest)
|
15
|
+
for this library, google-cloud-resource_manager, to see the convenience methods for
|
16
|
+
constructing client objects. Reference documentation for the client objects
|
17
|
+
themselves can be found in the client library documentation for the versioned
|
18
|
+
client gems:
|
19
|
+
[google-cloud-resource_manager-v3](https://cloud.google.com/ruby/docs/reference/google-cloud-resource_manager-v3/latest).
|
20
|
+
|
21
|
+
## Quick Start
|
22
|
+
|
23
|
+
```
|
24
|
+
$ gem install google-cloud-resource_manager
|
25
|
+
```
|
26
|
+
|
27
|
+
In order to use this library, you first need to go through the following steps:
|
28
|
+
|
29
|
+
1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
|
30
|
+
1. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
|
31
|
+
1. [Enable the API.](https://console.cloud.google.com/apis/library/cloudresourcemanager.googleapis.com)
|
32
|
+
1. {file:AUTHENTICATION.md Set up authentication.}
|
33
|
+
|
34
|
+
## Debug Logging
|
35
|
+
|
36
|
+
This library comes with opt-in Debug Logging that can help you troubleshoot
|
37
|
+
your application's integration with the API. When logging is activated, key
|
38
|
+
events such as requests and responses, along with data payloads and metadata
|
39
|
+
such as headers and client configuration, are logged to the standard error
|
40
|
+
stream.
|
41
|
+
|
42
|
+
**WARNING:** Client Library Debug Logging includes your data payloads in
|
43
|
+
plaintext, which could include sensitive data such as PII for yourself or your
|
44
|
+
customers, private keys, or other security data that could be compromising if
|
45
|
+
leaked. Always practice good data hygiene with your application logs, and follow
|
46
|
+
the principle of least access. Google also recommends that Client Library Debug
|
47
|
+
Logging be enabled only temporarily during active debugging, and not used
|
48
|
+
permanently in production.
|
49
|
+
|
50
|
+
To enable logging, set the environment variable `GOOGLE_SDK_RUBY_LOGGING_GEMS`
|
51
|
+
to the value `all`. Alternatively, you can set the value to a comma-delimited
|
52
|
+
list of client library gem names. This will select the default logging behavior,
|
53
|
+
which writes logs to the standard error stream. On a local workstation, this may
|
54
|
+
result in logs appearing on the console. When running on a Google Cloud hosting
|
55
|
+
service such as [Google Cloud Run](https://cloud.google.com/run), this generally
|
56
|
+
results in logs appearing alongside your application logs in the
|
57
|
+
[Google Cloud Logging](https://cloud.google.com/logging/) service.
|
58
|
+
|
59
|
+
Debug logging also requires that the versioned clients for this service be
|
60
|
+
sufficiently recent, released after about Dec 10, 2024. If logging is not
|
61
|
+
working, try updating the versioned clients in your bundle or installed gems:
|
62
|
+
[google-cloud-resource_manager-v3](https://cloud.google.com/ruby/docs/reference/google-cloud-resource_manager-v3/latest).
|
63
|
+
|
64
|
+
## Supported Ruby Versions
|
65
|
+
|
66
|
+
This library is supported on Ruby 3.0+.
|
67
|
+
|
68
|
+
Google provides official support for Ruby versions that are actively supported
|
69
|
+
by Ruby Core—that is, Ruby versions that are either in normal maintenance or
|
70
|
+
in security maintenance, and not end of life. Older versions of Ruby _may_
|
71
|
+
still work, but are unsupported and not recommended. See
|
72
|
+
https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby
|
73
|
+
support schedule.
|
74
|
+
|
75
|
+
## Which client should I use?
|
76
|
+
|
77
|
+
Most modern Ruby client libraries for Google APIs come in two flavors: the main
|
78
|
+
client library with a name such as `google-cloud-resource_manager`,
|
79
|
+
and lower-level _versioned_ client libraries with names such as
|
80
|
+
`google-cloud-resource_manager-v3`.
|
81
|
+
_In most cases, you should install the main client._
|
82
|
+
|
83
|
+
### What's the difference between the main client and a versioned client?
|
84
|
+
|
85
|
+
A _versioned client_ provides a basic set of data types and client classes for
|
86
|
+
a _single version_ of a specific service. (That is, for a service with multiple
|
87
|
+
versions, there might be a separate versioned client for each service version.)
|
88
|
+
Most versioned clients are written and maintained by a code generator.
|
89
|
+
|
90
|
+
The _main client_ is designed to provide you with the _recommended_ client
|
91
|
+
interfaces for the service. There will be only one main client for any given
|
92
|
+
service, even a service with multiple versions. The main client includes
|
93
|
+
factory methods for constructing the client objects we recommend for most
|
94
|
+
users. In some cases, those will be classes provided by an underlying versioned
|
95
|
+
client; in other cases, they will be handwritten higher-level client objects
|
96
|
+
with additional capabilities, convenience methods, or best practices built in.
|
97
|
+
Generally, the main client will default to a recommended service version,
|
98
|
+
although in some cases you can override this if you need to talk to a specific
|
99
|
+
service version.
|
100
|
+
|
101
|
+
### Why would I want to use the main client?
|
102
|
+
|
103
|
+
We recommend that most users install the main client gem for a service. You can
|
104
|
+
identify this gem as the one _without_ a version in its name, e.g.
|
105
|
+
`google-cloud-resource_manager`.
|
106
|
+
The main client is recommended because it will embody the best practices for
|
107
|
+
accessing the service, and may also provide more convenient interfaces or
|
108
|
+
tighter integration into frameworks and third-party libraries. In addition, the
|
109
|
+
documentation and samples published by Google will generally demonstrate use of
|
110
|
+
the main client.
|
111
|
+
|
112
|
+
### Why would I want to use a versioned client?
|
113
|
+
|
114
|
+
You can use a versioned client if you are content with a possibly lower-level
|
115
|
+
class interface, you explicitly want to avoid features provided by the main
|
116
|
+
client, or you want to access a specific service version not be covered by the
|
117
|
+
main client. You can identify versioned client gems because the service version
|
118
|
+
is part of the name, e.g. `google-cloud-resource_manager-v3`.
|
119
|
+
|
120
|
+
### What about the google-apis-<name> clients?
|
121
|
+
|
122
|
+
Client library gems with names that begin with `google-apis-` are based on an
|
123
|
+
older code generation technology. They talk to a REST/JSON backend (whereas
|
124
|
+
most modern clients talk to a [gRPC](https://grpc.io/) backend) and they may
|
125
|
+
not offer the same performance, features, and ease of use provided by more
|
126
|
+
modern clients.
|
127
|
+
|
128
|
+
The `google-apis-` clients have wide coverage across Google services, so you
|
129
|
+
might need to use one if there is no modern client available for the service.
|
130
|
+
However, if a modern client is available, we generally recommend it over the
|
131
|
+
older `google-apis-` clients.
|
@@ -1,4 +1,6 @@
|
|
1
|
-
#
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Copyright 2025 Google LLC
|
2
4
|
#
|
3
5
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
4
6
|
# you may not use this file except in compliance with the License.
|
@@ -12,11 +14,13 @@
|
|
12
14
|
# See the License for the specific language governing permissions and
|
13
15
|
# limitations under the License.
|
14
16
|
|
17
|
+
# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
|
18
|
+
|
15
19
|
|
16
20
|
module Google
|
17
21
|
module Cloud
|
18
22
|
module ResourceManager
|
19
|
-
VERSION = "0.
|
23
|
+
VERSION = "1.0.0"
|
20
24
|
end
|
21
25
|
end
|
22
26
|
end
|