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.
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
- # Copyright 2016 Google LLC
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.39.0".freeze
23
+ VERSION = "1.0.0"
20
24
  end
21
25
  end
22
26
  end