Viewing file:  OperationsGapicClient.php (17.53 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
<?php
/*
* Copyright 2017 Google LLC
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following disclaimer
* in the documentation and/or other materials provided with the
* distribution.
* * Neither the name of Google LLC nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/*
* GENERATED CODE WARNING
* This file was generated from the file
* https://github.com/google/googleapis/blob/master/google/longrunning/operations.proto
* and updates to that file get reflected here through a refresh process.
*
* EXPERIMENTAL: This client library class has not yet been declared GA (1.0). This means that
* even though we intend the surface to be stable, we may make backwards incompatible changes
* if necessary.
*
* @experimental
*/
namespace Google\ApiCore\LongRunning\Gapic;
use Google\ApiCore\ApiException;
use Google\ApiCore\Call;
use Google\ApiCore\GapicClientTrait;
use Google\ApiCore\RetrySettings;
use Google\ApiCore\RequestParamsHeaderDescriptor;
use Google\ApiCore\Transport\TransportInterface;
use Google\LongRunning\CancelOperationRequest;
use Google\LongRunning\DeleteOperationRequest;
use Google\LongRunning\GetOperationRequest;
use Google\LongRunning\ListOperationsRequest;
use Google\LongRunning\ListOperationsResponse;
use Google\LongRunning\Operation;
use Google\Protobuf\GPBEmpty;
/**
* Service Description: Manages long-running operations with an API service.
*
* When an API method normally takes long time to complete, it can be designed
* to return [Operation][google.longrunning.Operation] to the client, and the client can use this
* interface to receive the real response asynchronously by polling the
* operation resource, or pass the operation resource to another API (such as
* Google Cloud Pub/Sub API) to receive the response. Any API service that
* returns long-running operations should implement the `Operations` interface
* so developers can have a consistent client experience.
*
* EXPERIMENTAL: This client library class has not yet been declared GA (1.0). This means that
* even though we intend the surface to be stable, we may make backwards incompatible changes
* if necessary.
*
* This class provides the ability to make remote calls to the backing service through method
* calls that map to API methods. Sample code to get started:
*
* ```
* $options = [
* 'apiEndpoint' => 'my-service-address',
* 'scopes' => ['my-service-scope'],
* ];
* $operationsClient = new OperationsClient($options);
* try {
* $name = '';
* $response = $operationsClient->getOperation($name);
* } finally {
* if (isset($operationsClient)) {
* $operationsClient->close();
* }
* }
* ```
*
* @experimental
*/
class OperationsGapicClient
{
use GapicClientTrait;
/**
* The name of the service.
*/
const SERVICE_NAME = 'google.longrunning.Operations';
/**
* The default port of the service.
*/
const DEFAULT_SERVICE_PORT = 443;
/**
* The name of the code generator, to be included in the agent header.
*/
const CODEGEN_NAME = 'gapic';
private static function getClientDefaults()
{
return [
'serviceName' => self::SERVICE_NAME,
'clientConfig' => __DIR__.'/../resources/operations_client_config.json',
'descriptorsConfigPath' => __DIR__.'/../resources/operations_descriptor_config.php',
'credentialsConfig' => [
],
'transportConfig' => [
'rest' => [
'restClientConfigPath' => __DIR__.'/../resources/operations_rest_client_config.php'
],
],
];
}
/**
* Constructor.
*
* @param array $options {
* Required. Options for configuring the service API wrapper. Those options
* that must be provided are marked as Required.
*
* @type string $apiEndpoint
* Required. The address of the API remote host. May optionally include the port,
* formatted as "<uri>:<port>".
* @type string|array $credentials
* The credentials to be used by the client to authorize API calls. This option
* accepts either a path to a credentials file, or a decoded credentials file as a
* PHP array.
* *Advanced usage*: In addition, this option can also accept a pre-constructed
* \Google\Auth\FetchAuthTokenInterface object or \Google\ApiCore\CredentialsWrapper
* object. Note that when one of these objects are provided, any settings in
* $credentialsConfig will be ignored.
* @type array $credentialsConfig
* Options used to configure credentials, including auth token caching, for the client. For
* a full list of supporting configuration options, see
* \Google\ApiCore\CredentialsWrapper::build.
* @type bool $disableRetries
* Determines whether or not retries defined by the client configuration should be
* disabled. Defaults to `false`.
* @type string|array $clientConfig
* Client method configuration, including retry settings. This option can be either a
* path to a JSON file, or a PHP array containing the decoded JSON data.
* By default this settings points to the default client config file, which is provided
* in the resources folder.
* @type string $transport
* The transport used for executing network requests. May be either the string `rest`
* or `grpc`. Defaults to `grpc` if gRPC support is detected on the system.
* *Advanced usage*: Additionally, it is possible to pass in an already instantiated
* TransportInterface object. Note that when this objects is provided, any settings in
* $transportConfig, and any $apiEndpoint setting, will be ignored.
* @type array $transportConfig
* Configuration options that will be used to construct the transport. Options for
* each supported transport type should be passed in a key for that transport. For
* example:
* $transportConfig = [
* 'grpc' => [...],
* 'rest' => [...]
* ];
* See the GrpcTransport::build and RestTransport::build methods for the supported
* options.
* }
* @experimental
*/
public function __construct($options = [])
{
$clientOptions = $this->buildClientOptions($options);
$this->setClientOptions($clientOptions);
}
/**
* Gets the latest state of a long-running operation. Clients can use this
* method to poll the operation result at intervals as recommended by the API
* service.
*
* Sample code:
* ```
* $options = [
* 'apiEndpoint' => 'my-service-address',
* 'scopes' => ['my-service-scope'],
* ];
* $operationsClient = new OperationsClient($options);
* try {
* $name = '';
* $response = $operationsClient->getOperation($name);
* } finally {
* if (isset($operationsClient)) {
* $operationsClient->close();
* }
* }
* ```
*
* @param string $name The name of the operation resource.
* @param array $optionalArgs {
* Optional.
*
* @type RetrySettings|array $retrySettings
* Retry settings to use for this call. Can be a
* {@see Google\ApiCore\RetrySettings} object, or an associative array
* of retry settings parameters. See the documentation on
* {@see Google\ApiCore\RetrySettings} for example usage.
* }
*
* @return \Google\LongRunning\Operation
*
* @throws ApiException if the remote call fails
* @experimental
*/
public function getOperation($name, $optionalArgs = [])
{
$request = new GetOperationRequest();
$request->setName($name);
$requestParams = new RequestParamsHeaderDescriptor([
'name' => $request->getName(),
]);
$optionalArgs['headers'] = isset($optionalArgs['headers'])
? array_merge($requestParams->getHeader(), $optionalArgs['headers'])
: $requestParams->getHeader();
return $this->startCall(
'GetOperation',
Operation::class,
$optionalArgs,
$request
)->wait();
}
/**
* Lists operations that match the specified filter in the request. If the
* server doesn't support this method, it returns `UNIMPLEMENTED`.
*
* NOTE: the `name` binding below allows API services to override the binding
* to use different resource name schemes, such as `users/*/operations`.
*
* Sample code:
* ```
* $options = [
* 'apiEndpoint' => 'my-service-address',
* 'scopes' => ['my-service-scope'],
* ];
* $operationsClient = new OperationsClient($options);
* try {
* $name = '';
* $filter = '';
* // Iterate through all elements
* $pagedResponse = $operationsClient->listOperations($name, $filter);
* foreach ($pagedResponse->iterateAllElements() as $element) {
* // doSomethingWith($element);
* }
*
* // OR iterate over pages of elements
* $pagedResponse = $operationsClient->listOperations($name, $filter);
* foreach ($pagedResponse->iteratePages() as $page) {
* foreach ($page as $element) {
* // doSomethingWith($element);
* }
* }
* } finally {
* if (isset($operationsClient)) {
* $operationsClient->close();
* }
* }
* ```
*
* @param string $name The name of the operation collection.
* @param string $filter The standard list filter.
* @param array $optionalArgs {
* Optional.
*
* @type int $pageSize
* The maximum number of resources contained in the underlying API
* response. The API may return fewer values in a page, even if
* there are additional values to be retrieved.
* @type string $pageToken
* A page token is used to specify a page of values to be returned.
* If no page token is specified (the default), the first page
* of values will be returned. Any page token used here must have
* been generated by a previous call to the API.
* @type RetrySettings|array $retrySettings
* Retry settings to use for this call. Can be a
* {@see Google\ApiCore\RetrySettings} object, or an associative array
* of retry settings parameters. See the documentation on
* {@see Google\ApiCore\RetrySettings} for example usage.
* }
*
* @return \Google\ApiCore\PagedListResponse
*
* @throws ApiException if the remote call fails
* @experimental
*/
public function listOperations($name, $filter, $optionalArgs = [])
{
$request = new ListOperationsRequest();
$request->setName($name);
$request->setFilter($filter);
if (isset($optionalArgs['pageSize'])) {
$request->setPageSize($optionalArgs['pageSize']);
}
if (isset($optionalArgs['pageToken'])) {
$request->setPageToken($optionalArgs['pageToken']);
}
$requestParams = new RequestParamsHeaderDescriptor([
'name' => $request->getName(),
]);
$optionalArgs['headers'] = isset($optionalArgs['headers'])
? array_merge($requestParams->getHeader(), $optionalArgs['headers'])
: $requestParams->getHeader();
return $this->getPagedListResponse(
'ListOperations',
$optionalArgs,
ListOperationsResponse::class,
$request
);
}
/**
* Starts asynchronous cancellation on a long-running operation. The server
* makes a best effort to cancel the operation, but success is not
* guaranteed. If the server doesn't support this method, it returns
* `google.rpc.Code.UNIMPLEMENTED`. Clients can use
* [Operations.GetOperation][google.longrunning.Operations.GetOperation] or
* other methods to check whether the cancellation succeeded or whether the
* operation completed despite cancellation. On successful cancellation,
* the operation is not deleted; instead, it becomes an operation with
* an [Operation.error][google.longrunning.Operation.error] value with a [google.rpc.Status.code][google.rpc.Status.code] of 1,
* corresponding to `Code.CANCELLED`.
*
* Sample code:
* ```
* $options = [
* 'apiEndpoint' => 'my-service-address',
* 'scopes' => ['my-service-scope'],
* ];
* $operationsClient = new OperationsClient($options);
* try {
* $name = '';
* $operationsClient->cancelOperation($name);
* } finally {
* if (isset($operationsClient)) {
* $operationsClient->close();
* }
* }
* ```
*
* @param string $name The name of the operation resource to be cancelled.
* @param array $optionalArgs {
* Optional.
*
* @type RetrySettings|array $retrySettings
* Retry settings to use for this call. Can be a
* {@see Google\ApiCore\RetrySettings} object, or an associative array
* of retry settings parameters. See the documentation on
* {@see Google\ApiCore\RetrySettings} for example usage.
* }
*
* @throws ApiException if the remote call fails
* @experimental
*/
public function cancelOperation($name, $optionalArgs = [])
{
$request = new CancelOperationRequest();
$request->setName($name);
$requestParams = new RequestParamsHeaderDescriptor([
'name' => $request->getName(),
]);
$optionalArgs['headers'] = isset($optionalArgs['headers'])
? array_merge($requestParams->getHeader(), $optionalArgs['headers'])
: $requestParams->getHeader();
return $this->startCall(
'CancelOperation',
GPBEmpty::class,
$optionalArgs,
$request
)->wait();
}
/**
* Deletes a long-running operation. This method indicates that the client is
* no longer interested in the operation result. It does not cancel the
* operation. If the server doesn't support this method, it returns
* `google.rpc.Code.UNIMPLEMENTED`.
*
* Sample code:
* ```
* $options = [
* 'apiEndpoint' => 'my-service-address',
* 'scopes' => ['my-service-scope'],
* ];
* $operationsClient = new OperationsClient($options);
* try {
* $name = '';
* $operationsClient->deleteOperation($name);
* } finally {
* if (isset($operationsClient)) {
* $operationsClient->close();
* }
* }
* ```
*
* @param string $name The name of the operation resource to be deleted.
* @param array $optionalArgs {
* Optional.
*
* @type RetrySettings|array $retrySettings
* Retry settings to use for this call. Can be a
* {@see Google\ApiCore\RetrySettings} object, or an associative array
* of retry settings parameters. See the documentation on
* {@see Google\ApiCore\RetrySettings} for example usage.
* }
*
* @throws ApiException if the remote call fails
* @experimental
*/
public function deleteOperation($name, $optionalArgs = [])
{
$request = new DeleteOperationRequest();
$request->setName($name);
$requestParams = new RequestParamsHeaderDescriptor([
'name' => $request->getName(),
]);
$optionalArgs['headers'] = isset($optionalArgs['headers'])
? array_merge($requestParams->getHeader(), $optionalArgs['headers'])
: $requestParams->getHeader();
return $this->startCall(
'DeleteOperation',
GPBEmpty::class,
$optionalArgs,
$request
)->wait();
}
}
|