class OperationsClient

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 beta. This class may change more frequently than those which have been declared beta or 1.0, including changes which break backwards compatibility.

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:

try {
    $options = [
        'serviceAddress' => 'my-service-address',
        'scopes' => ['my-service-scope'],
    ];
    $operationsClient = new OperationsClient($options);
    $name = "";
    $response = $operationsClient->getOperation($name);
} finally {
    if (isset($operationsClient)) {
        $operationsClient->close();
    }
}

Constants

DEFAULT_SERVICE_PORT

The default port of the service.

DEFAULT_TIMEOUT_MILLIS

The default timeout for non-retrying methods.

CODEGEN_NAME

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

CODEGEN_VERSION

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

Methods

__construct(array $options = [])

Constructor.

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.

close()

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

Details

at line 187
__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 $serviceAddress Required. The domain name of the API remote host.
@type mixed $port The port on which to connect to the remote host. Default 443.
@type \Grpc\ChannelCredentials $sslCreds
      A `ChannelCredentials` for use with an SSL-enabled channel.
      Default: a credentials object returned from
      \Grpc\ChannelCredentials::createSsl()
@type array $scopes Required. A string array of scopes to use when acquiring credentials.
@type array $retryingOverride
      An associative array of string => RetryOptions, where the keys
      are method names (e.g. 'createFoo'), that overrides default retrying
      settings. A value of null indicates that the method in question should
      not retry.
@type int $timeoutMillis The timeout in milliseconds to use for calls
                         that don't use retries. For calls that use retries,
                         set the timeout in RetryOptions.
                         Default: 30000 (30 seconds)
@type \Google\Auth\CredentialsLoader $credentialsLoader
                         A CredentialsLoader object created using the
                         Google\Auth library.

}

Exceptions

ValidationException Throws a ValidationException if required arguments are missing from the $options array.

at line 297
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:

try {
    $options = [
        'serviceAddress' => 'my-service-address',
        'scopes' => ['my-service-scope'],
    ];
    $operationsClient = new OperationsClient($options);
    $name = "";
    $response = $operationsClient->getOperation($name);
} finally {
    if (isset($operationsClient)) {
        $operationsClient->close();
    }
}

Parameters

string $name The name of the operation resource.
array $optionalArgs { Optional.

@type \Google\GAX\RetrySettings $retrySettings
     Retry settings to use for this call. If present, then
     $timeoutMillis is ignored.
@type int $timeoutMillis
     Timeout to use for this call. Only used if $retrySettings
     is not set.

}

Return Value

Operation

Exceptions

ApiException if the remote call fails

at line 382
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/*/operations.

Sample code:

try {
    $options = [
        'serviceAddress' => 'my-service-address',
        'scopes' => ['my-service-scope'],
    ];
    $operationsClient = new OperationsClient($options);
    $name = "";
    $filter = "";
    // Iterate through all elements
    $pagedResponse = $operationsClient->listOperations($name, $filter);
    foreach ($pagedResponse->iterateAllElements() as $element) {
        // doSomethingWith($element);
    }

    // OR iterate over pages of elements, with the maximum page size set to 5
    $pagedResponse = $operationsClient->listOperations($name, $filter, ['pageSize' => 5]);
    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 \Google\GAX\RetrySettings $retrySettings
     Retry settings to use for this call. If present, then
     $timeoutMillis is ignored.
@type int $timeoutMillis
     Timeout to use for this call. Only used if $retrySettings
     is not set.

}

Return Value

PagedListResponse

Exceptions

ApiException if the remote call fails

at line 454
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:

try {
    $options = [
        'serviceAddress' => 'my-service-address',
        'scopes' => ['my-service-scope'],
    ];
    $operationsClient = new OperationsClient($options);
    $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 \Google\GAX\RetrySettings $retrySettings
     Retry settings to use for this call. If present, then
     $timeoutMillis is ignored.
@type int $timeoutMillis
     Timeout to use for this call. Only used if $retrySettings
     is not set.

}

Exceptions

ApiException if the remote call fails

at line 513
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:

try {
    $options = [
        'serviceAddress' => 'my-service-address',
        'scopes' => ['my-service-scope'],
    ];
    $operationsClient = new OperationsClient($options);
    $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 \Google\GAX\RetrySettings $retrySettings
     Retry settings to use for this call. If present, then
     $timeoutMillis is ignored.
@type int $timeoutMillis
     Timeout to use for this call. Only used if $retrySettings
     is not set.

}

Exceptions

ApiException if the remote call fails

at line 540
close()

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