Google Cloud Build V1 Client - Class PublishBuildEventClient (0.3.8)

Reference documentation and code samples for the Google Cloud Build V1 Client class PublishBuildEventClient.

Service Description: A service for publishing BuildEvents. BuildEvents are generated by Build Systems to record actions taken during a Build. Events occur in streams, are identified by a StreamId, and ordered by sequence number in a stream.

A Build may contain several streams of BuildEvents, depending on the systems that are involved in the Build. Some BuildEvents are used to declare the beginning and end of major portions of a Build; these are called LifecycleEvents, and are used (for example) to indicate the beginning or end of a Build, and the beginning or end of an Invocation attempt (there can be more than 1 Invocation in a Build if, for example, a failure occurs somewhere and it needs to be retried).

Other, build-tool events represent actions taken by the Build tool, such as target objects produced via compilation, tests run, et cetera. There could be more than one build tool stream for an invocation attempt of a build.

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:

$publishBuildEventClient = new PublishBuildEventClient();
try {
    $orderedBuildEvent = new OrderedBuildEvent();
    $projectId = 'project_id';
    $request = new PublishBuildToolEventStreamRequest();
    $request->setOrderedBuildEvent($orderedBuildEvent);
    $request->setProjectId($projectId);
    // Write all requests to the server, then read all responses until the
    // stream is complete
    $requests = [
        $request,
    ];
    $stream = $publishBuildEventClient->publishBuildToolEventStream();
    $stream->writeAll($requests);
    foreach ($stream->closeWriteAndReadAll() as $element) {
        // doSomethingWith($element);
    }
    // Alternatively:
    // Write requests individually, making read() calls if
    // required. Call closeWrite() once writes are complete, and read the
    // remaining responses from the server.
    $requests = [
        $request,
    ];
    $stream = $publishBuildEventClient->publishBuildToolEventStream();
    foreach ($requests as $request) {
        $stream->write($request);
        // if required, read a single response from the stream
        $element = $stream->read();
        // doSomethingWith($element)
    }
    $stream->closeWrite();
    $element = $stream->read();
    while (!is_null($element)) {
        // doSomethingWith($element)
        $element = $stream->read();
    }
} finally {
    $publishBuildEventClient->close();
}

Methods

__construct

Constructor.

Parameters
Name	Description
`options`	`array` Optional. Options for configuring the service API wrapper.
`↳ serviceAddress`	`string` Deprecated. This option will be removed in a future major release. Please utilize the `$apiEndpoint` option instead.
`↳ apiEndpoint`	`string` The address of the API remote host. May optionally include the port, formatted as "
`↳ credentials`	`string\|array\|FetchAuthTokenInterface\|CredentialsWrapper` 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.
`↳ credentialsConfig`	`array` 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() .
`↳ disableRetries`	`bool` Determines whether or not retries defined by the client configuration should be disabled. Defaults to `false`.
`↳ clientConfig`	`string\|array` 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.
`↳ transport`	`string\|TransportInterface` 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 Google\ApiCore\Transport\TransportInterface object. Note that when this object is provided, any settings in $transportConfig, and any $serviceAddress setting, will be ignored.
`↳ transportConfig`	`array` 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 Google\ApiCore\Transport\GrpcTransport::build() and Google\ApiCore\Transport\RestTransport::build() methods for the supported options.
`↳ clientCertSource`	`callable` A callable which returns the client cert as a string. This can be used to provide a certificate and private key to the transport layer for mTLS.

publishBuildToolEventStream

Publish build tool events belonging to the same stream to a backend job using bidirectional streaming.

Sample code:

$publishBuildEventClient = new PublishBuildEventClient();
try {
    $orderedBuildEvent = new OrderedBuildEvent();
    $projectId = 'project_id';
    $request = new PublishBuildToolEventStreamRequest();
    $request->setOrderedBuildEvent($orderedBuildEvent);
    $request->setProjectId($projectId);
    // Write all requests to the server, then read all responses until the
    // stream is complete
    $requests = [
        $request,
    ];
    $stream = $publishBuildEventClient->publishBuildToolEventStream();
    $stream->writeAll($requests);
    foreach ($stream->closeWriteAndReadAll() as $element) {
        // doSomethingWith($element);
    }
    // Alternatively:
    // Write requests individually, making read() calls if
    // required. Call closeWrite() once writes are complete, and read the
    // remaining responses from the server.
    $requests = [
        $request,
    ];
    $stream = $publishBuildEventClient->publishBuildToolEventStream();
    foreach ($requests as $request) {
        $stream->write($request);
        // if required, read a single response from the stream
        $element = $stream->read();
        // doSomethingWith($element)
    }
    $stream->closeWrite();
    $element = $stream->read();
    while (!is_null($element)) {
        // doSomethingWith($element)
        $element = $stream->read();
    }
} finally {
    $publishBuildEventClient->close();
}

Parameters
Name	Description
`optionalArgs`	`array` Optional.
`↳ timeoutMillis`	`int` Timeout to use for this call.

Returns
Type	Description
`Google\ApiCore\BidiStream`

publishLifecycleEvent

Publish a build event stating the new state of a build (typically from the build queue). The BuildEnqueued event must be publishd before all other events for the same build ID.

The backend will persist the event and deliver it to registered frontend jobs immediately without batching.

The commit status of the request is reported by the RPC's util_status() function. The error code is the canoncial error code defined in //util/task/codes.proto.

Sample code:

$publishBuildEventClient = new PublishBuildEventClient();
try {
    $buildEvent = new OrderedBuildEvent();
    $projectId = 'project_id';
    $publishBuildEventClient->publishLifecycleEvent($buildEvent, $projectId);
} finally {
    $publishBuildEventClient->close();
}

Parameters
Name	Description
`buildEvent`	`Google\Cloud\Build\V1\OrderedBuildEvent` Required. The lifecycle build event. If this is a build tool event, the RPC will fail with INVALID_REQUEST.
`projectId`	`string` Required. The project this build is associated with. This should match the project used for the initial call to PublishLifecycleEvent (containing a BuildEnqueued message).
`optionalArgs`	`array` Optional.
`↳ serviceLevel`	`int` The interactivity of this build. For allowed values, use constants defined on Google\Cloud\Build\V1\PublishLifecycleEventRequest\ServiceLevel
`↳ streamTimeout`	`Duration` If the next event for this build or invocation (depending on the event type) hasn't been published after this duration from when {build_event} is written to BES, consider this stream expired. If this field is not set, BES backend will use its own default value.
`↳ notificationKeywords`	`string[]` Additional information about a build request. These are define by the event publishers, and the Build Event Service does not validate or interpret them. They are used while notifying internal systems of new builds and invocations if the OrderedBuildEvent.event type is BuildEnqueued/InvocationAttemptStarted.
`↳ checkPrecedingLifecycleEventsPresent`	`bool` Whether to require a previously received matching parent lifecycle event for the current request's event before continuing processing. - InvocationAttemptStarted and BuildFinished events require a BuildEnqueued parent event. - InvocationAttemptFinished events require an InvocationAttemptStarted parent event.
`↳ retrySettings`	`RetrySettings\|array` Retry settings to use for this call. Can be a Google\ApiCore\RetrySettings object, or an associative array of retry settings parameters. See the documentation on Google\ApiCore\RetrySettings for example usage.

Constants

SERVICE_NAME

Value: 'google.devtools.build.v1.PublishBuildEvent'

The name of the service.

SERVICE_ADDRESS

Value: 'buildeventservice.googleapis.com'

The default address of the service.

DEFAULT_SERVICE_PORT

Value: 443

The default port of the service.

CODEGEN_NAME

Value: 'gapic'

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