REST Resource: forms.watches

Resource: Watch

A watch for events for a form. When the designated event happens, a notification will be published to the specified target. The notification's attributes will include a formId key that has the ID of the watched form and an eventType key that has the string of the type.

Messages are sent with at-least-once delivery and are only dropped in extraordinary circumstances. Typically all notifications should be reliably delivered within a few seconds; however, in some situations notifications may be delayed.

A watch expires seven days after it is created unless it is renewed with watches.renew

JSON representation 
{
  "id": string,
  "target": {
    object (WatchTarget)
  },
  "eventType": enum (EventType),
  "createTime": string,
  "expireTime": string,
  "errorType": enum (ErrorType),
  "state": enum (State)
}
Fields
id

string

Output only. The ID of this watch. See notes on CreateWatchRequest.watch_id.
target

object (WatchTarget)

Required. Where to send the notification.
eventType

enum (EventType)

Required. Which event type to watch for.
createTime

string (Timestamp format)

Output only. Timestamp of when this was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
expireTime

string (Timestamp format)

Output only. Timestamp for when this will expire. Each watches.renew call resets this to seven days in the future.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
errorType

enum (ErrorType)

Output only. The most recent error type for an attempted delivery. To begin watching the form again a call can be made to watches.renew which also clears this error information.
state

enum (State)

Output only. The current state of the watch. Additional details about suspended watches can be found by checking the errorType.

WatchTarget

The target for notification delivery.

JSON representation 
{

  // Union field target can be only one of the following:
  "topic": {
    object (CloudPubsubTopic)
  }
  // End of list of possible types for union field target.
}
Fields
Union field target. Required. The target for notification delivery. target can be only one of the following:
topic

object (CloudPubsubTopic)

A Pub/Sub topic. To receive notifications, the topic must grant publish privileges to the Forms service account serviceAccount:forms-notifications@system.gserviceaccount.com. Only the project that owns a topic may create a watch with it.

Pub/Sub delivery guarantees should be considered.

CloudPubsubTopic

A Pub/Sub topic.

JSON representation 
{
  "topicName": string
}
Fields
topicName

string

Required. A fully qualified Pub/Sub topic name to publish the events to. This topic must be owned by the calling project and already exist in Pub/Sub.

EventType

Possible event types that can be watched.

Enums
EVENT_TYPE_UNSPECIFIED Unspecified event type. This value should not be used.
SCHEMA The schema event type. A watch with this event type will be notified about changes to form content and settings.
RESPONSES The responses event type. A watch with this event type will be notified when form responses are submitted.

ErrorType

Possible error types.

Enums
ERROR_TYPE_UNSPECIFIED Unspecified error type.
PROJECT_NOT_AUTHORIZED The cloud project does not have access to the form being watched. This occurs if the user has revoked the authorization for your project to access their form(s). Watches with this error will not be retried. To attempt to begin watching the form again a call can be made to watches.renew
NO_USER_ACCESS The user that granted access no longer has access to the form being watched. Watches with this error will not be retried. To attempt to begin watching the form again a call can be made to watches.renew
OTHER_ERRORS Another type of error has occurred. Whether notifications will continue depends on the watch state.

State

Possible Watch states.

Enums
STATE_UNSPECIFIED Unspecified state.
ACTIVE Watch is active.
SUSPENDED The watch is suspended due to an error that may be resolved. The watch will continue to exist until it expires. To attempt to reactivate the watch a call can be made to watches.renew

Methods

create

 Create a new watch.

delete

 Delete a watch.

list

 Return a list of the watches owned by the invoking project.

renew

 Renew an existing watch for seven days.