google. protobuf
Abstract types
Any
Any
contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message.
Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type.
Example 1: Pack and unpack a message in C++.
Foo foo = ...;
Any any;
any.PackFrom(foo);
...
if (any.UnpackTo(&foo)) {
...
}
Example 2: Pack and unpack a message in Java.
Foo foo = ...;
Any any = Any.pack(foo);
...
if (any.is(Foo.class)) {
foo = any.unpack(Foo.class);
}
Example 3: Pack and unpack a message in Python.
foo = Foo(...)
any = Any()
any.Pack(foo)
...
if any.Is(Foo.DESCRIPTOR):
any.Unpack(foo)
...
Example 4: Pack and unpack a message in Go
foo := &pb.Foo{...}
any, err := ptypes.MarshalAny(foo)
...
foo := &pb.Foo{}
if err := ptypes.UnmarshalAny(any, foo); err != nil {
...
}
The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".
JSON
The JSON representation of an Any
value uses the regular representation of the deserialized, embedded message, with an additional field @type
which contains the type URL. Example:
package google.profile;
message Person {
string first_name = 1;
string last_name = 2;
}
{
"@type": "type.googleapis.com/google.profile.Person",
"firstName": <string>,
"lastName": <string>
}
If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field
value
which holds the custom JSON in addition to the @type
field. Example (for message google.protobuf.Duration):
{
"@type": "type.googleapis.com/google.protobuf.Duration",
"value": "1.212s"
}
Properties
Parameter |
|
---|---|
typeUrl |
string
A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. The last segment of the URL's path must represent the fully qualified name of the type (as in
In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme
|
value |
string Must be a valid serialized protocol buffer of the above specified type. |
BoolValue
Wrapper message for bool
.
The JSON representation for BoolValue
is JSON true
and false
.
Property
Parameter |
|
---|---|
value |
boolean The bool value. |
BytesValue
Wrapper message for bytes
.
The JSON representation for BytesValue
is JSON string.
Property
Parameter |
|
---|---|
value |
string The bytes value. |
DoubleValue
Wrapper message for double
.
The JSON representation for DoubleValue
is JSON number.
Property
Parameter |
|
---|---|
value |
number The double value. |
Empty
A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance:
service Foo {
rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}
The JSON representation for Empty
is empty JSON object {}
.
FloatValue
Wrapper message for float
.
The JSON representation for FloatValue
is JSON number.
Property
Parameter |
|
---|---|
value |
number The float value. |
Int32Value
Wrapper message for int32
.
The JSON representation for Int32Value
is JSON number.
Property
Parameter |
|
---|---|
value |
number The int32 value. |
Int64Value
Wrapper message for int64
.
The JSON representation for Int64Value
is JSON string.
Property
Parameter |
|
---|---|
value |
number The int64 value. |
StringValue
Wrapper message for string
.
The JSON representation for StringValue
is JSON string.
Property
Parameter |
|
---|---|
value |
string The string value. |
Timestamp
A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings. See https://www.ietf.org/rfc/rfc3339.txt.
Examples
Example 1: Compute Timestamp from POSIX time()
.
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX gettimeofday()
.
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec 1000);
Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime()
.
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) 100));
Example 4: Compute Timestamp from Java System.currentTimeMillis()
.
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the standard
toISOString() with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's ISODateTimeFormat.dateTime()
to obtain a formatter capable of generating timestamps in this format.
Properties
Parameter |
|
---|---|
seconds |
number Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. |
nanos |
number Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive. |
UInt32Value
Wrapper message for uint32
.
The JSON representation for UInt32Value
is JSON number.
Property
Parameter |
|
---|---|
value |
number The uint32 value. |
UInt64Value
Wrapper message for uint64
.
The JSON representation for UInt64Value
is JSON string.
Property
Parameter |
|
---|---|
value |
number The uint64 value. |