Google Cloud C++ Client
2.2.1
C++ Client Library for Google Cloud Platform
|
Contains all the Google Cloud C++ Library APIs. More...
Classes | |
struct | AsyncTimerResult |
The result of an async timer operation. More... | |
class | AsyncOperation |
Represents a pending asynchronous operation. More... | |
class | AsyncStreamingReadWriteRpc |
A streaming read-write RPC. More... | |
class | BackgroundThreads |
A object representing the background threads available to a Client. More... | |
struct | EndpointOption |
Change the endpoint. More... | |
struct | UserAgentProductsOption |
User-agent products to include with each request. More... | |
struct | TracingComponentsOption |
Return whether tracing is enabled for the given component . More... | |
struct | UserProjectOption |
Specifies a project for quota and billing purposes. More... | |
struct | AuthorityOption |
Configure the "authority" attribute. More... | |
class | CompletionQueue |
Call the functor associated with asynchronous operations when they complete. More... | |
class | ConnectionOptions |
The configuration parameters for client connections. More... | |
class | Credentials |
The public interface for Google's Unified Auth Client (GUAC) library. More... | |
struct | DelegatesOption |
Configure the delegates for MakeImpersonateServiceAccountCredentials() More... | |
struct | ScopesOption |
Configure the scopes for MakeImpersonateServiceAccountCredentials() More... | |
struct | AccessTokenLifetimeOption |
Configure the access token lifetime. More... | |
struct | UnifiedCredentialsOption |
A wrapper to store credentials into an options. More... | |
struct | CARootsFilePathOption |
Configures a custom CA (Certificates Authority) certificates file. More... | |
struct | ExperimentalTag |
An argument type to indicate experimental functions. More... | |
class | future |
Implement ISO/IEC TS 19571:2016 future<T> . More... | |
class | promise |
Implement promise<T> as defined in ISO/IEC TS 19571:2016. More... | |
class | future< void > |
Implement ISO/IEC TS 19571:2016 future for void. More... | |
class | promise< void > |
Specialize promise as defined in ISO/IEC TS 19571:2016 for void. More... | |
struct | GrpcCredentialOption |
The gRPC credentials used by clients configured with this object. More... | |
struct | GrpcNumChannelsOption |
The number of transport channels to create. More... | |
struct | GrpcChannelArgumentsOption |
A string-string map of arguments for grpc::ChannelArguments::SetString . More... | |
struct | GrpcChannelArgumentsNativeOption |
The native grpc::ChannelArguments object. More... | |
struct | GrpcTracingOptionsOption |
The TracingOptions to use when printing grpc protocol buffer messages. More... | |
struct | GrpcBackgroundThreadPoolSizeOption |
The size of the background thread pool. More... | |
struct | GrpcCompletionQueueOption |
The CompletionQueue to use for background gRPC work. More... | |
struct | GrpcBackgroundThreadsFactoryOption |
Changes the BackgroundThreadsFactory . More... | |
class | KmsKeyName |
This class identifies a Google Cloud KMS Key. More... | |
struct | LogRecord |
Represents a single log message. More... | |
class | LogBackend |
The logging backend interface. More... | |
class | LogSink |
A sink to receive log records. More... | |
struct | NullStream |
Implements operator<< for all types, without any effect. More... | |
class | Logger |
Define the class to capture a log message. More... | |
class | Logger< false > |
Define the logger for a disabled log level. More... | |
class | Options |
A class that holds option structs indexed by their type. More... | |
class | PollingPolicy |
Control the Cloud C++ client library behavior with respect to polling on long running operations. More... | |
class | GenericPollingPolicy |
Construct a polling policy from existing Retry and Backoff policies. More... | |
class | Project |
This class identifies a Cloud Project. More... | |
class | ErrorInfo |
Describes the cause of the error with structured details. More... | |
class | Status |
Represents success or an error with info about the error. More... | |
class | RuntimeStatusError |
A runtime error that wraps a google::cloud::Status . More... | |
class | StatusOr |
Holds a value or a Status indicating why there is no value. More... | |
class | StreamRange |
A StreamRange<T> is a range of StatusOr<T> where the end-of-stream is indicated by a non-OK Status . More... | |
class | TracingOptions |
The configuration parameters for RPC/protobuf tracing. More... | |
Typedefs | |
using | BackoffPolicy = ::google::cloud::internal::BackoffPolicy |
The base class for backoff policies. More... | |
using | ExponentialBackoffPolicy = google::cloud::internal::ExponentialBackoffPolicy |
A truncated exponential backoff policy with randomized periods. More... | |
using | CommonOptionList = OptionList< EndpointOption, UserAgentProductsOption, TracingComponentsOption, UserProjectOption, AuthorityOption > |
A list of all the common options. More... | |
using | UnifiedCredentialsOptionList = OptionList< AccessTokenLifetimeOption, CARootsFilePathOption, DelegatesOption, ScopesOption, UnifiedCredentialsOption > |
A list of GUAC options. More... | |
using | BackgroundThreadsFactory = std::function< std::unique_ptr< BackgroundThreads >()> |
using | GrpcOptionList = OptionList< GrpcCredentialOption, GrpcNumChannelsOption, GrpcChannelArgumentsOption, GrpcChannelArgumentsNativeOption, GrpcTracingOptionsOption, GrpcBackgroundThreadPoolSizeOption, GrpcCompletionQueueOption, GrpcBackgroundThreadsFactoryOption > |
A list of all the gRPC options. More... | |
using | IamUpdater = std::function< absl::optional< google::iam::v1::Policy >(google::iam::v1::Policy)> |
Used in the SetIamPolicy() read-modify-write cycles where an etag helps prevent simultaneous updates of a policy from overwriting each other. More... | |
template<typename T > | |
using | optional = absl::optional< T > |
Alias template for google::cloud::optional. More... | |
template<typename... T> | |
using | OptionList = internal::TypeList< T... > |
A template to hold a list of "option" types. More... | |
Enumerations | |
enum class | Idempotency { kIdempotent , kNonIdempotent } |
Whether a request is idempotent. More... | |
enum class | Severity : int { GCP_LS_TRACE , GCP_LS_DEBUG , GCP_LS_INFO , GCP_LS_NOTICE , GCP_LS_WARNING , GCP_LS_ERROR , GCP_LS_CRITICAL , GCP_LS_ALERT , GCP_LS_FATAL , GCP_LS_HIGHEST = GCP_LS_FATAL , GCP_LS_LOWEST = GCP_LS_TRACE , GCP_LS_LOWEST_ENABLED = GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED } |
Define the severity levels for Google Cloud Platform C++ Libraries logging. More... | |
enum class | StatusCode { kOk = 0 , kCancelled = 1 , kUnknown = 2 , kInvalidArgument = 3 , kDeadlineExceeded = 4 , kNotFound = 5 , kAlreadyExists = 6 , kPermissionDenied = 7 , kUnauthenticated = 16 , kResourceExhausted = 8 , kFailedPrecondition = 9 , kAborted = 10 , kOutOfRange = 11 , kUnimplemented = 12 , kInternal = 13 , kUnavailable = 14 , kDataLoss = 15 } |
Well-known status codes with grpc::StatusCode -compatible values. More... | |
Functions | |
std::shared_ptr< Credentials > | MakeInsecureCredentials () |
Create insecure (aka anonymous, aka unauthenticated) credentials. More... | |
std::shared_ptr< Credentials > | MakeGoogleDefaultCredentials () |
Creates the default credentials. More... | |
std::shared_ptr< Credentials > | MakeAccessTokenCredentials (std::string const &access_token, std::chrono::system_clock::time_point expiration) |
Creates credentials with a fixed access token. More... | |
std::shared_ptr< Credentials > | MakeImpersonateServiceAccountCredentials (std::shared_ptr< Credentials > base_credentials, std::string target_service_account, Options opts={}) |
Creates credentials for service account impersonation. More... | |
std::shared_ptr< Credentials > | MakeServiceAccountCredentials (std::string json_object) |
Creates service account credentials from a service account key. More... | |
template<typename T > | |
future< typename internal::make_ready_return< T >::type > | make_ready_future (T &&t) |
Create a future<void> that is immediately ready. More... | |
future< void > | make_ready_future () |
Create a future<void> that is immediately ready. More... | |
google::cloud::Status | MakeStatusFromRpcError (grpc::Status const &status) |
Creates a google::cloud::Status from a grpc::Status. More... | |
google::cloud::Status | MakeStatusFromRpcError (grpc::StatusCode code, std::string what) |
Creates a google::cloud::Status from a grpc::StatusCode and description. More... | |
google::cloud::Status | MakeStatusFromRpcError (google::rpc::Status const &proto) |
Creates a google::cloud::Status from a google:rpc::Status proto. More... | |
StatusOr< KmsKeyName > | MakeKmsKeyName (std::string const &full_name) |
Constructs a KmsKeyName from the given full_name . More... | |
std::ostream & | operator<< (std::ostream &os, Severity x) |
Streaming operator, writes a human readable representation. More... | |
std::ostream & | operator<< (std::ostream &os, LogRecord const &rhs) |
Default formatting of a LogRecord. More... | |
StatusOr< Project > | MakeProject (std::string const &full_name) |
Constructs a Project from the given full_name . More... | |
std::string | StatusCodeToString (StatusCode code) |
std::ostream & | operator<< (std::ostream &os, StatusCode code) |
template<typename T > | |
bool | operator== (StatusOr< T > const &a, StatusOr< T > const &b) |
template<typename T > | |
bool | operator!= (StatusOr< T > const &a, StatusOr< T > const &b) |
template<typename T > | |
StatusOr< T > | make_status_or (T rhs) |
constexpr int | version_major () |
The Google Cloud Storage C++ Client major version. More... | |
constexpr int | version_minor () |
The Google Cloud Storage C++ Client minor version. More... | |
constexpr int | version_patch () |
The Google Cloud Storage C++ Client patch version. More... | |
constexpr int | version () |
A single integer representing the Major/Minor/Patch version. More... | |
std::string | version_string () |
The version as a string, in MAJOR.MINOR.PATCH+gitrev format. More... | |
Control behaviour on unrecoverable errors. | |
The following APIs are google::cloud counterpart for std::{set,get}_terminate functions. If exceptions are not enabled via GOOGLE_CLOUD_CPP_HAVE_EXCEPTIONS, calling any function from throw_delegate.h will result in calling the handler installed via this API. By default, a call to std::abort() is used. | |
using | TerminateHandler = std::function< void(char const *msg)> |
Terminate handler. More... | |
TerminateHandler | SetTerminateHandler (TerminateHandler f) |
Install terminate handler and get the old one atomically. More... | |
TerminateHandler | GetTerminateHandler () |
Get the currently installed handler. More... | |
void | Terminate (char const *msg) |
Invoke the currently installed handler. More... | |
Contains all the Google Cloud C++ Library APIs.
using google::cloud::BackgroundThreadsFactory = typedef std::function<std::unique_ptr<BackgroundThreads>()> |
Definition at line 127 of file grpc_options.h.
using google::cloud::BackoffPolicy = typedef ::google::cloud::internal::BackoffPolicy |
The base class for backoff policies.
Definition at line 26 of file backoff_policy.h.
using google::cloud::CommonOptionList = typedef OptionList<EndpointOption, UserAgentProductsOption, TracingComponentsOption, UserProjectOption, AuthorityOption> |
A list of all the common options.
Definition at line 104 of file common_options.h.
using google::cloud::ExponentialBackoffPolicy = typedef google::cloud::internal::ExponentialBackoffPolicy |
A truncated exponential backoff policy with randomized periods.
Definition at line 29 of file backoff_policy.h.
A list of all the gRPC options.
Definition at line 153 of file grpc_options.h.
using google::cloud::IamUpdater = typedef std::function<absl::optional<google::iam::v1::Policy>( google::iam::v1::Policy)> |
Used in the SetIamPolicy()
read-modify-write cycles where an etag
helps prevent simultaneous updates of a policy from overwriting each other.
The updater is called with a recently fetched policy, and should either return an empty optional if no changes are required, or return a new policy to be set. In the latter case the updater should either (1) set the etag
of the returned policy to that of the recently fetched policy (strongly suggested), or (2) not set the etag
at all.
In case (1) if the etag
does not match the existing policy (i.e., there has been an intermediate update), this update is dropped and a new cycle is initiated. In case (2) the existing policy is overwritten blindly.
Definition at line 41 of file iam_updater.h.
using google::cloud::optional = typedef absl::optional<T> |
Alias template for google::cloud::optional.
absl::optional<T>
directly. Definition at line 31 of file optional.h.
using google::cloud::OptionList = typedef internal::TypeList<T...> |
A template to hold a list of "option" types.
This can be a useful way to create meaningful lists of options. For example, there could be a list containing all the gRPC options. Or a list of all ProductX options. This gives us a way to link to lists of options with doxygen, and to do some checking about what options a function may expect.
using google::cloud::TerminateHandler = typedef std::function<void(char const* msg)> |
Terminate handler.
It should handle the error, whose description are given in msg and should never return.
Definition at line 41 of file terminate_handler.h.
using google::cloud::UnifiedCredentialsOptionList = typedef OptionList<AccessTokenLifetimeOption, CARootsFilePathOption, DelegatesOption, ScopesOption, UnifiedCredentialsOption> |
A list of GUAC options.
Definition at line 299 of file credentials.h.
|
strong |
Whether a request is idempotent.
When a RPC fails with a retryable error, the google-cloud-cpp
client libraries automatically retry the RPC if the RPC is idempotent. For each service, the library define a policy that determines whether a given request is idempotent. In many cases this can be determined statically, for example, read-only operations are always idempotent. In some cases, the contents of the request may need to be examined to determine if the operation is idempotent. For example, performing operations with pre-conditions, such that the pre-conditions change when the operation succeed, is typically idempotent.
Applications may override the default idempotency policy, though we anticipate that this would be needed only in very rare circumstances. A few examples include:
Enumerator | |
---|---|
kIdempotent | The operation is idempotent and can be retried after a transient failure. |
kNonIdempotent | The operation is not idempotent and should not be retried after a transient failure. |
Definition at line 55 of file idempotency.h.
|
strong |
Define the severity levels for Google Cloud Platform C++ Libraries logging.
These are modelled after the severity level in syslog(1) and many derived tools.
We force the enum to be represented as an int
because we will store the values in an std::atomic<>
and the implementations usually optimize std::atomic<int>
but not std::atomic<Foo>
Enumerator | |
---|---|
GCP_LS_TRACE | Use this level for messages that indicate the code is entering and leaving functions. |
GCP_LS_DEBUG | Use this level for debug messages that should not be present in production. |
GCP_LS_INFO | Informational messages, such as normal progress. |
GCP_LS_NOTICE | Informational messages, such as unusual, but expected conditions. |
GCP_LS_WARNING | An indication of problems, users may need to take action. |
GCP_LS_ERROR | An error has been detected. Do not use for normal conditions, such as remote servers disconnecting. |
GCP_LS_CRITICAL | The system is in a critical state, such as running out of local resources. |
GCP_LS_ALERT | The system is at risk of immediate failure. |
GCP_LS_FATAL | The system is unusable. GCP_LOG(FATAL) will call std::abort(). |
GCP_LS_HIGHEST | The highest possible severity level. |
GCP_LS_LOWEST | The lowest possible severity level. |
GCP_LS_LOWEST_ENABLED | The lowest level that is enabled at compile-time. |
|
strong |
Well-known status codes with grpc::StatusCode
-compatible values.
The semantics of these values are documented in: https://grpc.io/grpc/cpp/classgrpc_1_1_status.html
TerminateHandler google::cloud::GetTerminateHandler | ( | ) |
Get the currently installed handler.
|
inline |
Create a future<void> that is immediately ready.
Definition at line 207 of file future_void.h.
|
inline |
Create a future<void> that is immediately ready.
Definition at line 217 of file future_generic.h.
StatusOr<T> google::cloud::make_status_or | ( | T | rhs | ) |
Definition at line 294 of file status_or.h.
std::shared_ptr<Credentials> google::cloud::MakeAccessTokenCredentials | ( | std::string const & | access_token, |
std::chrono::system_clock::time_point | expiration | ||
) |
Creates credentials with a fixed access token.
These credentials are useful when using an out-of-band mechanism to fetch access tokens. Note that access tokens are time limited, you will need to manually refresh the tokens created by the
std::shared_ptr<Credentials> google::cloud::MakeGoogleDefaultCredentials | ( | ) |
Creates the default credentials.
These are the most commonly used credentials, and are expected to meet the needs of most applications. The Google Default Credentials conform to aip/4110. Consider using these credentials when:
GOOGLE_APPLICATION_CREDENTIALS
environment variable to override the defaults. This environment variable should point to a file containing a service account key file, or a JSON object describing your user credentials.std::shared_ptr<Credentials> google::cloud::MakeImpersonateServiceAccountCredentials | ( | std::shared_ptr< Credentials > | base_credentials, |
std::string | target_service_account, | ||
Options | opts = {} |
||
) |
Creates credentials for service account impersonation.
Service account impersonation allows one account (user or service account) to act as a second account. This can be useful in multi-tenant services, where the service may perform some actions with an specific account associated with a tenant. The tenant can grant or restrict permissions to this tenant account.
When using service account impersonation is important to distinguish between the credentials used to obtain the target account credentials (the base_credentials
) parameter, and the credentials representing the target_service_account
.
Use AccessTokenLifetimeOption
to configure the maximum lifetime of the obtained credentials. The default is 1h (3600s), see IAM quotas for the limits set by the platform and how to override them.
Use DelegatesOption
to configure a sequence of intermediate service account, each of which has permissions to impersonate the next and the last one has permissions to impersonate target_service_account
.
Use ScopesOption
to restrict the authentication scope for the obtained credentials. See below for possible values.
std::shared_ptr<Credentials> google::cloud::MakeInsecureCredentials | ( | ) |
Create insecure (aka anonymous, aka unauthenticated) credentials.
These credentials are mostly intended for testing. Integration tests running against an emulator do not need to authenticate. In fact, it may be impossible to connect to an emulator using SSL/TLS because the emulators typically run without secure communication.
In addition, unit tests may benefit from using these credentials: loading the default credentials unnecessarily slows down the unit tests, and in some CI environments the credentials may fail to load, creating confusing warnings and sometimes even errors.
StatusOr<KmsKeyName> google::cloud::MakeKmsKeyName | ( | std::string const & | full_name | ) |
Constructs a KmsKeyName
from the given full_name
.
Returns a non-OK Status if full_name
is improperly formed.
std::shared_ptr<Credentials> google::cloud::MakeServiceAccountCredentials | ( | std::string | json_object | ) |
Creates service account credentials from a service account key.
A service account is an account for an application or compute workload instead of an individual end user. The recommended practice is to use Google Default Credentials, which relies on the configuration of the Google Cloud system hosting your application (GCE, GKE, Cloud Run) to authenticate your workload or application. But sometimes you may need to create and download a service account key, for example, to use a service account when running your application on a system that is not part of Google Cloud.
Service account credentials are used in this latter case.
You can create multiple service account keys for a single service account. When you create a service account key, the key is returned as string, in the format described by aip/4112. This string contains an id for the service account, as well as the cryptographical materials (a RSA private key) required to authenticate the caller.
Therefore, services account keys should be treated as any other secret with security implications. Think of them as unencrypted passwords. Do not store them where unauthorized persons or programs may read them.
As stated above, most applications should probably use default credentials, maybe pointing them to a file with these contents. Using this function may be useful when the service account key is obtained from Cloud Secret Manager or a similar service.
google::cloud::Status google::cloud::MakeStatusFromRpcError | ( | google::rpc::Status const & | proto | ) |
Creates a google::cloud::Status
from a google:rpc::Status
proto.
Some gRPC services return the google::rpc::Status
proto for errors. The libraries in google-cloud-cpp
represent these errors using a google::cloud::Status
.
google::cloud::Status google::cloud::MakeStatusFromRpcError | ( | grpc::Status const & | status | ) |
Creates a google::cloud::Status from a grpc::Status.
google::cloud::Status google::cloud::MakeStatusFromRpcError | ( | grpc::StatusCode | code, |
std::string | what | ||
) |
Creates a google::cloud::Status from a grpc::StatusCode and description.
bool google::cloud::operator!= | ( | StatusOr< T > const & | a, |
StatusOr< T > const & | b | ||
) |
Definition at line 289 of file status_or.h.
std::ostream& google::cloud::operator<< | ( | std::ostream & | os, |
LogRecord const & | rhs | ||
) |
Default formatting of a LogRecord.
std::ostream& google::cloud::operator<< | ( | std::ostream & | os, |
Severity | x | ||
) |
Streaming operator, writes a human readable representation.
std::ostream& google::cloud::operator<< | ( | std::ostream & | os, |
StatusCode | code | ||
) |
bool google::cloud::operator== | ( | StatusOr< T > const & | a, |
StatusOr< T > const & | b | ||
) |
Definition at line 281 of file status_or.h.
TerminateHandler google::cloud::SetTerminateHandler | ( | TerminateHandler | f | ) |
Install terminate handler and get the old one atomically.
f | the handler. It should never return, behaviour is undefined otherwise. |
std::string google::cloud::StatusCodeToString | ( | StatusCode | code | ) |
void google::cloud::Terminate | ( | char const * | msg | ) |
Invoke the currently installed handler.
msg | Details about the error. |
This function should never return.
|
constexpr |
|
constexpr |
The Google Cloud Storage C++ Client major version.
|
constexpr |
The Google Cloud Storage C++ Client minor version.
|
constexpr |
The Google Cloud Storage C++ Client patch version.
std::string google::cloud::version_string | ( | ) |
The version as a string, in MAJOR.MINOR.PATCH+gitrev format.