class OperationsGapicClient (View source)

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();
    }
}

Traits

Common functions used to work with various clients.

Provides basic array helper methods.

Provides helper methods for gRPC support.

Constants

SERVICE_NAME

The name of the service.

DEFAULT_SERVICE_PORT

The default port of the service.

CODEGEN_NAME

The name of the code generator, to be included in the agent header.

Methods

static array
validate(array $arr, array $requiredKeys)

No description

static array
validateNotNull(array $arr, array $requiredKeys)

No description

close()

Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.

__construct(array $options = [])

Constructor.

Operation
getOperation(string $name, array $optionalArgs = [])

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.

listOperations(string $name, string $filter, array $optionalArgs = [])

Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns UNIMPLEMENTED.

cancelOperation(string $name, array $optionalArgs = [])

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.

deleteOperation(string $name, array $optionalArgs = [])

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.

Details

static array validate(array $arr, array $requiredKeys)

No description

Parameters

array $arr

Associative array

array $requiredKeys

List of keys to check for in $arr

Return Value

array

Returns $arr for fluent use

static array validateNotNull(array $arr, array $requiredKeys)

No description

Parameters

array $arr

Associative array

array $requiredKeys

List of keys to check for in $arr

Return Value

array

Returns $arr for fluent use

close()

Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.

__construct(array $options = [])

Constructor.

Parameters

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.

}

Operation getOperation(string $name, array $optionalArgs = [])

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();
    }
}

Parameters

string $name

The name of the operation resource.

array $optionalArgs

{ Optional.

@type RetrySettings|array $retrySettings
     Retry settings to use for this call. Can be a
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} object, or an associative array
     of retry settings parameters. See the documentation on
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} for example usage.

}

Return Value

Operation

Exceptions

ApiException

PagedListResponse listOperations(string $name, string $filter, array $optionalArgs = [])

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/&#42;/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();
    }
}

Parameters

string $name

The name of the operation collection.

string $filter

The standard list filter.

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
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} object, or an associative array
     of retry settings parameters. See the documentation on
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} for example usage.

}

Return Value

PagedListResponse

Exceptions

ApiException

cancelOperation(string $name, array $optionalArgs = [])

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();
    }
}

Parameters

string $name

The name of the operation resource to be cancelled.

array $optionalArgs

{ Optional.

@type RetrySettings|array $retrySettings
     Retry settings to use for this call. Can be a
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} object, or an associative array
     of retry settings parameters. See the documentation on
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} for example usage.

}

Exceptions

ApiException

deleteOperation(string $name, array $optionalArgs = [])

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();
    }
}

Parameters

string $name

The name of the operation resource to be deleted.

array $optionalArgs

{ Optional.

@type RetrySettings|array $retrySettings
     Retry settings to use for this call. Can be a
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} object, or an associative array
     of retry settings parameters. See the documentation on
     {\Google\ApiCore\LongRunning\Gapic\Google\ApiCore\RetrySettings} for example usage.

}

Exceptions

ApiException