Sui 풀 노드 gRPC 메시지 및 타입 정의
이 페이지는 Sui 풀 노드 gRPC API의 모든 메시지, enum, scalar 타입 정의를 나열한다.
sui/rpc/v2/ledger_service.proto
Messages
object_id,version,digest.sequence_number,digest.object_id,version,digest.mainnet, testnet, and so on.sui/rpc/v2/signature_verification_service.proto
Messages
PersonalMessage and TransactionData and the Bcs.name must be set to indicate which type of message is being verified.sui/rpc/v2/checkpoint.proto
Messages
transactions.objects field will not be populated.sui/rpc/v2/transaction_execution_service.proto
Messages
An intermediate result/output from the execution of a single command
effects.status,checkpoint.UserSignatures authorizing the execution of the provided transaction.Response message for NodeService.ExecuteTransaction.
checks is DISABLED.Enums
ENABLEDDISABLEDsui/rpc/v2/event.proto
Messages
An event.
MoveCall command that triggered this event to be emitted.MoveCall command that triggered this event to be emitted.sui/rpc/v2/input.proto
Messages
An input to a user transaction.
NON_EXCLUSIVE_WRITE mutability variant requires providing a new field. The old mutable field will continue to be populated and respected as an input for the time being.kind is IMMUTABLE_OR_OWNED or RECEIVING or if kind is SHARED this is the initial version of the object when it was sharedEnums
SOURCE_UNKNOWNSENDERSPONSORINPUT_KIND_UNKNOWNPUREIMMUTABLE_OR_OWNEDSHAREDRECEIVINGFUNDS_WITHDRAWALMUTABILITY_UNKNOWNIMMUTABLEMUTABLENON_EXCLUSIVE_WRITEsui/rpc/v2/executed_transaction.proto
Messages
TransactionEvents for this transaction. This field might be empty, even if it was explicitly requested, if the transaction didn't produce any events. sui.types.TransactionEffects.events_digest is populated if the transaction produced any events.sui/rpc/v2/error_reason.proto
Enums
ERROR_REASON_UNKNOWNFIELD_INVALIDFIELD_MISSINGsui/rpc/v2/subscription_service.proto
Messages
Request message for SubscriptionService.SubscribeCheckpoints
Response message for SubscriptionService.SubscribeCheckpoints
sui/rpc/v2/bcs.proto
Messages
sui/rpc/v2/balance_change.proto
Messages
The delta, or change, in balance for an address for a particular Coin type.
sui/rpc/v2/signature_scheme.proto
Enums
ED25519SECP256K1SECP256R1MULTISIGBLS12381ZKLOGINPASSKEYsui/rpc/v2/jwk.proto
Messages
A JSON web key.
Struct that contains info for a JWK. A list of them for different kinds can be retrieved from the JWK endpoint (for example, &#lt;https://www.googleapis.com/oauth2/v3/certs>). The JWK is used to verify the JWT token.
sui/rpc/v2/object.proto
Messages
A rendered JSON blob based on an on-chain template.
null or not set.null, and will be accompanied by a field in errors, explaining the error.An object on the Sui blockchain.
Display template.Set of Objects
sui/rpc/v2/system_state.proto
Messages
A message that represents a Move 0x2::table::Table or 0x2::bag::Bag
A staking pool embedded in each validator struct in the system state object.
None if the pool is pre-active and Some(<epoch_number>) if active or inactive.None = {pre-active, active}, Some(<epoch_number>) if in-active, and it was de-activated at epoch <epoch_number>.activation_epoch of this pool and contains exchange rates at the beginning of each epoch, i.e., right after the rewards for the previous epoch have been deposited into the pool. key: u64 (epoch number), value: PoolTokenExchangeRateStakedSui object, updated at epoch boundaries.Struct representing the onchain storage fund.
storage_rebate of all objects currently stored on-chain. To maintain this invariant, the only inflow of this balance is storage charges collected from transactions, and the only outflow is storage rebates of transactions, including both the portion refunded to the transaction senders as well as the non-refundable portion taken out and put into non_refundable_balance.validator_low_stake_threshold for this many epochs before being kicked out.validator_low_stake_threshold are considered to have low stake and will be escorted out of the validator set after being below this threshold for more than validator_low_stake_grace_period number of epochs.validator_very_low_stake_threshold will be removed immediately at epoch change, no grace period.safe_mode_ are accumulated during safe mode when advance_epoch_safe_mode is executed. They will eventually be processed once we are out of safe mode.Definition of a Validator in the system contracts
Note: fields of ValidatorMetadata are flattened into this type
ValidatorMetadata structactive_validators it is added to this table so that stakers can continue to withdraw their stake from it. key: address (staking pool Id), value: 0x3::validator_wrapper::ValidatorWrapperactive_validators.advance_epoch function.Validator structs. When an address calls request_add_validator_candidate, they get added to this table and become a preactive validator. When the candidate has met the min stake requirement, they can call request_add_validator to officially add them to the active validator set active_validators next epoch. key: address (sui address of the validator), value: 0x3::validator_wrapper::ValidatorWrappersui/rpc/v2/effects.proto
Messages
Input/output state of an object that was changed during execution.
output_state is OUTPUT_OBJECT_STATE_ACCUMULATOR_WRITEThe effects of executing a transaction.
None if the transaction does not emit any event.changed_objects vector. System transactions that don't require gas will leave this as None.A consensus object that wasn't changed during execution.
Enums
ACCUMULATOR_OPERATION_UNKNOWNMERGESPLITID_OPERATION_UNKNOWNNONECREATEDDELETEDINPUT_OBJECT_STATE_UNKNOWNINPUT_OBJECT_STATE_DOES_NOT_EXISTINPUT_OBJECT_STATE_EXISTSOUTPUT_OBJECT_STATE_UNKNOWNOUTPUT_OBJECT_STATE_DOES_NOT_EXISTOUTPUT_OBJECT_STATE_OBJECT_WRITEOUTPUT_OBJECT_STATE_PACKAGE_WRITEOUTPUT_OBJECT_STATE_ACCUMULATOR_WRITEUNCHANGED_CONSENSUS_OBJECT_KIND_UNKNOWNREAD_ONLY_ROOTMUTATE_CONSENSUS_STREAM_ENDEDREAD_CONSENSUS_STREAM_ENDEDCANCELEDPER_EPOCH_CONFIGsui/rpc/v2/checkpoint_contents.proto
Messages
The committed to contents of a checkpoint.
Transaction information committed to in a checkpoint.
AddressAliases object version, if any, that was used to verify the UserSignature at the same position in signatures. This field is present when CheckpointContents.version is >= 2.sui/rpc/v2/move_package.proto
Messages
Describes a Move Datatype.
defining_id is the storage_id of the package version that first introduced or added that type.Descriptor of a field that belongs to a struct or enum variant
Descriptor of a Move function
Upgraded package info for the linkage table.
A Move Module.
Representation of a type signature that could appear as a function parameter or return value.
Representation of a type signature that could appear as a field type for a struct or enum
type is TYPE_PARAMETERA Move Package
original_id (sometimes also called its runtime_id) is the storage_id of the first version of this package that has been published. The original_id/runtime_id is stable across all versions of the package and does not ever change.storage_id is the Sui ObjectId of the package on-chain. Outside of system packages the storage_id for every package version is different.Identifies a struct and the module it was defined in.
A generic type parameter used in the declaration of a struct or enum.
Descriptor of an enum variant
Enums
Ability classifies what operations are permitted for a given typeABILITY_UNKNOWNCOPYDROPSTOREKEYDATATYPE_KIND_UNKNOWNSTRUCTENUMVISIBILITY_UNKNOWNPRIVATEPUBLICFRIENDREFERENCE_UNKNOWNIMMUTABLEMUTABLETYPE_UNKNOWNADDRESSBOOLU8U16U32U64U128U256VECTORDATATYPETYPE_PARAMETERsui/rpc/v2/argument.proto
Messages
An argument to a programmable transaction command.
Enums
ARGUMENT_KIND_UNKNOWNGASINPUTProgrammableTransaction inputs).RESULTProgrammableTransaction commands).sui/rpc/v2/name_service.proto
Messages
@name as well as name.sui formats.Field<Domain,NameRecord>.RegistrationNFT assigned to this record. The owner of the corresponding RegistrationNFT has the rights to be able to change and adjust the target_address of this domain. It is possible that the ID changes if the record expires and is purchased by someone else.sui/rpc/v2/protocol_config.proto
Messages
sui/rpc/v2/owner.proto
Messages
Enum of different types of ownership for an object.
Enums
OWNER_KIND_UNKNOWNADDRESSOBJECTSHAREDIMMUTABLECONSENSUS_ADDRESSsui/rpc/v2/move_package_service.proto
Messages
1000 entries will be returned. The maximum value is 10000; values above 10000 will be coerced to 10000.ListPackageVersions call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListPackageVersions must match the call that provided the page token.page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.sui/rpc/v2/state_service.proto
Messages
Balance information for a specific coin type.
coin_type in its smallest unit. This is the sum of all spendable amounts of coin_type (address_balance and coin_balance).Metadata for a coin type
0x2::coin::CoinMetadata object or 0x2::sui::coin_registry::Currency object (when registered with CoinRegistry).Information about a coin type's 0x2::coin::TreasuryCap and its total available supply
Request message for LiveDataService.GetBalance.
Response message for LiveDataService.GetBalance.
Return the total coin balance for one coin type, owned by the address owner.
Request message for NodeService.GetCoinInfo.
Response message for NodeService.GetCoinInfo.
0x2::coin::CoinMetadata if it exists and has not been wrapped.0x2::coin::RegulatedCoinMetadata object for coins that have not been migrated to the CoinRegistry If this coin is not known to be regulated, only the coin_regulated_state field will be populated.0x2::coin::TreasuryCap if it exists and has not been wrapped.Request message for LiveDataService.ListBalances.
50 entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.ListBalances call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListBalances must match the call that provided the page token.Response message for LiveDataService.ListBalances.
Return the total coin balance for all coin types, owned by the address owner.
Request message for NodeService.ListDynamicFields
50 entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.ListDynamicFields call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListDynamicFields must match the call that provided the page token.parent,field_id.Response message for NodeService.ListDynamicFields
page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.0x2::coin::Coin will return all Coin<T> objects regardless of the type parameter T. Providing a type with a type param will restrict the returned objects to only those objects that match the provided type parameters, e.g. 0x2::coin::Coin<0x2::sui::SUI> will only return Coin<SUI> objects.50 entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.ListOwnedObjects call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListOwnedObjects must match the call that provided the page token.object_id,version,object_type.Information about a regulated coin, which indicates that it makes use of the transfer deny list.
0x2::coin::RegulatedCoinMetadata object. Only present for coins that have not been migrated to CoinRegistry.Enums
METADATA_CAP_STATE_UNKNOWNCLAIMEDUNCLAIMEDDELETEDSUPPLY_STATE_UNKNOWNFIXEDBURN_ONLYDYNAMIC_FIELD_KIND_UNKNOWNFIELDOBJECTCOIN_REGULATED_STATE_UNKNOWN0x2::coin::RegulatedCoinMetadata object.REGULATEDUNREGULATEDsui/rpc/v2/signature.proto
Messages
A G1 point.
A G2 point.
Aggregated signature from members of a multisig committee.
A multisig committee.
A member in a multisig committee.
Set of valid public keys for multisig committee members.
A signature from a member of a multisig committee.
A passkey authenticator.
See
struct.PasskeyAuthenticator
for more information on the requirements on the shape of the
client_data_json field.
Either an ed25519, secp256k1 or secp256r1 signature
A signature from a user.
MULTISIG.PASSKEY.ZKLOGIN.An aggregated signature from multiple validators.
ValidatorCommittee from this epoch to verify this signature.The validator set for a particular epoch.
A member of a validator committee.
A zklogin authenticator.
A claim of the iss in a zklogin proof.
A zklogin groth16 proof and the required inputs to perform proof verification.
A zklogin groth16 proof.
sui/rpc/v2/execution_status.proto
Messages
An error with an argument to a command.
Set of objects that were congested, leading to the transaction's cancellation.
An error that can occur during the execution of a transaction.
The status of an executed transaction.
Location in Move bytecode where an error occurred.
An error with upgrading a package.
A size error.
Type argument error.
Enums
COMMAND_ARGUMENT_ERROR_KIND_UNKNOWNTYPE_MISMATCHINVALID_BCS_BYTESINVALID_USAGE_OF_PURE_ARGUMENTINVALID_ARGUMENT_TO_PRIVATE_ENTRY_FUNCTIONINDEX_OUT_OF_BOUNDSindex field will be set indicating the invalid index value.SECONDARY_INDEX_OUT_OF_BOUNDSindex and subresult fields will be set indicating the invalid index value.INVALID_RESULT_ARITYindex field will be set indicating the invalid index value.INVALID_GAS_COIN_USAGETransferObject command.INVALID_VALUE_USAGEINVALID_OBJECT_BY_VALUEINVALID_OBJECT_BY_MUT_REF&mut.CONSENSUS_OBJECT_OPERATION_NOT_ALLOWEDINVALID_ARGUMENT_ARITYINVALID_TRANSFER_OBJECTstore abilityINVALID_MAKE_MOVE_VEC_NON_OBJECT_ARGUMENTARGUMENT_WITHOUT_VALUECANNOT_MOVE_BORROWED_VALUEcopy ability; although in rare cases, it could also be this is the last usage of a value without the drop ability.CANNOT_WRITE_TO_EXTENDED_REFERENCEINVALID_REFERENCE_ARGUMENTEXECUTION_ERROR_KIND_UNKNOWNINSUFFICIENT_GASINVALID_GAS_OBJECTGas object.INVARIANT_VIOLATIONFEATURE_NOT_YET_SUPPORTEDOBJECT_TOO_BIGPACKAGE_TOO_BIGCIRCULAR_OBJECT_OWNERSHIPINSUFFICIENT_COIN_BALANCECOIN_BALANCE_OVERFLOWPUBLISH_ERROR_NON_ZERO_ADDRESSSUI_MOVE_VERIFICATION_ERRORMOVE_PRIMITIVE_RUNTIME_ERRORMOVE_ABORTVM_VERIFICATION_OR_DESERIALIZATION_ERRORVM_INVARIANT_VIOLATIONFUNCTION_NOT_FOUNDARITY_MISMATCHTYPE_ARITY_MISMATCHNON_ENTRY_FUNCTION_INVOKEDCOMMAND_ARGUMENT_ERRORTYPE_ARGUMENT_ERRORUNUSED_VALUE_WITHOUT_DROPINVALID_PUBLIC_FUNCTION_RETURN_TYPEINVALID_TRANSFER_OBJECTEFFECTS_TOO_LARGEPUBLISH_UPGRADE_MISSING_DEPENDENCYPUBLISH_UPGRADE_DEPENDENCY_DOWNGRADEPACKAGE_UPGRADE_ERRORWRITTEN_OBJECTS_TOO_LARGECERTIFICATE_DENIEDSUI_MOVE_VERIFICATION_TIMEDOUTCONSENSUS_OBJECT_OPERATION_NOT_ALLOWEDINPUT_OBJECT_DELETEDEXECUTION_CANCELED_DUE_TO_CONSENSUS_OBJECT_CONGESTIONADDRESS_DENIED_FOR_COINCOIN_TYPE_GLOBAL_PAUSEEXECUTION_CANCELED_DUE_TO_RANDOMNESS_UNAVAILABLEMOVE_VECTOR_ELEM_TOO_BIGMOVE_RAW_VALUE_TOO_BIGINVALID_LINKAGEINSUFFICIENT_FUNDS_FOR_WITHDRAWNON_EXCLUSIVE_WRITE_INPUT_OBJECT_MODIFIEDPACKAGE_UPGRADE_ERROR_KIND_UNKNOWNUNABLE_TO_FETCH_PACKAGENOT_A_PACKAGEINCOMPATIBLE_UPGRADEDIGEST_DOES_NOT_MATCHUNKNOWN_UPGRADE_POLICYPACKAGE_ID_DOES_NOT_MATCHPackageId in upgrade ticket.TYPE_ARGUMENT_ERROR_KIND_UNKNOWNTYPE_NOT_FOUNDCONSTRAINT_NOT_SATISFIEDsui/rpc/v2/object_reference.proto
Messages
sui/rpc/v2/transaction.proto
Messages
A new JWK.
Expire old JWKs.
Update the set of valid JWKs.
A transaction that was canceled.
System transaction used to change the epoch.
ChangeEpoch txn, the validator must write out the following modules. Modules are provided with the version they will be upgraded to, their modules in serialized form (which include their package ID), and a list of their transitive dependencies.A single command in a programmable transaction.
forall T: Vec<T> -> vector<T> Given n-values of the same type, it constructs a vector. For non-objects or an empty vector, the type tag must be specified.(&mut Coin<T>, Vec<Coin<T>>) It merges n-coins into the first coin.(&mut Coin<T>, Vec<u64>) -> Vec<Coin<T>> It splits off some amounts into new coins with those amounts.(Vec<forall T:key+store. T>, address) It sends n-objects to the specified address. These objects must have store (public transfer) and either the previous owner must be an address or the object must be newly created.UpgradeTicket that must have been produced from an earlier command in the same programmable transaction.Consensus commit prologue system transaction.
This message can represent V1, V2, and V3 prologue types.
Version assignments performed by consensus.
Set of operations run at the end of the epoch to close out the current epoch and start the next one.
Operation run at the end of an epoch.
Payment information for executing a transaction.
Command to build a Move vector out of a set of individual elements.
Command to merge multiple coins of the same type into a single coin.
Command to call a Move function.
Functions that can be called by a MoveCall command are those that have a function signature
that is either entry or public (which don't have a reference return type).
A user transaction.
Contains a series of native commands and Move calls where the results of one command can be used in future commands.
Command to publish a new Move package.
Randomness update.
Command to split a single coin object into multiple coins.
System package.
A transaction.
A TTL for a transaction.
Transaction type.
ChangeEpoch variant is now deprecated (but the ChangeEpoch struct is still used by EndOfEpochTransaction).Command to transfer ownership of a set of objects to an address.
Command to upgrade an already published package.
Object version assignment from consensus.
Enums
KIND_UNKNOWNCHANGE_EPOCHAUTHENTICATOR_STATE_CREATEAUTHENTICATOR_STATE_EXPIRERANDOMNESS_STATE_CREATEDENY_LIST_STATE_CREATEBRIDGE_STATE_CREATEBRIDGE_COMMITTEE_INITSTORE_EXECUTION_TIME_OBSERVATIONSACCUMULATOR_ROOT_CREATECOIN_REGISTRY_CREATEDISPLAY_REGISTRY_CREATEADDRESS_ALIAS_STATE_CREATEWRITE_ACCUMULATOR_STORAGE_COSTEXECUTION_TIME_OBSERVATION_KIND_UNKNOWNMOVE_ENTRY_POINTTRANSFER_OBJECTSSPLIT_COINSMERGE_COINSPUBLISHMAKE_MOVE_VECTORUPGRADETRANSACTION_EXPIRATION_KIND_UNKNOWNNONEEPOCHVALID_DURINGKIND_UNKNOWNPROGRAMMABLE_TRANSACTIONCHANGE_EPOCHChangeEpoch variant is now deprecated (but the ChangeEpoch struct is still used by EndOfEpochTransaction).GENESISCONSENSUS_COMMIT_PROLOGUE_V1AUTHENTICATOR_STATE_UPDATEEND_OF_EPOCHRANDOMNESS_STATE_UPDATECONSENSUS_COMMIT_PROLOGUE_V2CONSENSUS_COMMIT_PROLOGUE_V3CONSENSUS_COMMIT_PROLOGUE_V4PROGRAMMABLE_SYSTEM_TRANSACTIONsui/rpc/v2/epoch.proto
Messages
0x3::sui_system::SystemState) at the beginning of the epoch, for past epochs, or the current state for the current epoch.sui/rpc/v2/checkpoint_summary.proto
Messages
A commitment made by a checkpoint.
A header for a checkpoint on the Sui blockchain.
On the Sui network, checkpoints define the history of the blockchain. They are quite similar to the concept of blocks used by other blockchains like Bitcoin or Ethereum. The Sui blockchain, however, forms checkpoints after transaction execution has already happened to provide a certified history of the chain, instead of being formed before execution.
Checkpoints commit to a variety of state, including but not limited to:
- The hash of the previous checkpoint.
- The set of transaction digests, their corresponding effects digests, as well as the set of user signatures that authorized its execution.
- The objects produced by a transaction.
- The set of live objects that make up the current state of the chain.
- On epoch transitions, the next validator committee.
CheckpointSummarys themselves don't directly include all of the previous information but they
are the top-level type by which all the information is committed to transitively via cryptographic
hashes included in the summary. CheckpointSummarys are signed and certified by a quorum of
the validator committee in a given epoch to allow verification of the chain's state.
CheckpointSummary. This will be None only for the first, or genesis, checkpoint.CheckpointSummary is not an evolvable structure - it must be readable by any version of the code. Therefore, to allow extensions to be added to CheckpointSummary, opaque data can be added to checkpoints, which can be deserialized based on the current protocol version.Data, which when included in a CheckpointSummary, signals the end of an Epoch.
ValidatorCommittee for the next epoch.Enums
CHECKPOINT_COMMITMENT_KIND_UNKNOWNECMH_LIVE_OBJECT_SETCHECKPOINT_ARTIFACTSsui/rpc/v2/gas_cost_summary.proto
Messages
Summary of gas charges.
google/protobuf/timestamp.proto
Messages
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.
Restricting to that range ensures that conversion to
and from RFC 3339 date strings is possible.
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) &#lt;&#lt; 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 (so up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required, though only UTC (as indicated by "Z") is presently supported.
For example, 2017-01-15T01:30:15.01Z encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, you can convert a Date object to this format using the
standard toISOString()
method. In Python, you can convert a standard datetime.datetime object
to this format using strftime
with the time format spec %Y-%m-%dT%H:%M:%S.%fZ. Likewise, in Java, you
can use the Joda Time's ISODateTimeFormat.dateTime()
to obtain a formatter capable of generating timestamps in this format.
1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.google/protobuf/any.proto
Messages
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); } // or ... if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); }
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 := anypb.New(foo) if err != nil { ... } ... foo := &pb.Foo{} if err := any.UnmarshalTo(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": &#lt;string>, "lastName": &#lt;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" }
path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted). 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 http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.google/protobuf/duration.proto
Messages
A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.
Examples
Example 1: Compute Duration from two Timestamps in pseudo code.
Timestamp start = ...; Timestamp end = ...; Duration duration = ...;
duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos;
if (duration.seconds &#lt; 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos &#lt; 0) { duration.seconds -= 1; duration.nanos += 1000000000; }
Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
Timestamp start = ...; Duration duration = ...; Timestamp end = ...;
end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos;
if (end.nanos &#lt; 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; }
Example 3: Compute Duration from datetime.timedelta in Python.
td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td)
JSON Mapping
In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".
seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.google/protobuf/struct.proto
Messages
ListValue is a wrapper around a repeated field of values.
The JSON representation for ListValue is JSON array.
Struct represents a structured data value, consisting of fields
which map to dynamically typed values. In some languages, Struct
might be supported by a native representation. For example, in
scripting languages like JS a struct is represented as an
object. The details of that representation are described together
with the proto support for the language.
The JSON representation for Struct is JSON object.
Value represents a dynamically typed value which can be either
null, a number, a string, a boolean, a recursive struct value, or a
list of values. A producer of value is expected to set one of these
variants. Absence of any variant indicates an error.
The JSON representation for Value is JSON value.
Value.Enums
NullValue is a singleton enumeration to represent the null value for the Value type union. The JSON representation for NullValue is JSON null.NULL_VALUEgoogle/protobuf/field_mask.proto
Messages
FieldMask represents a set of symbolic field paths, for example:
paths: "f.a" paths: "f.b.d"
Here f represents a field in some root message, a and b
fields in the message found in f, and d a field found in the
message in f.b.
Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below).
Field Masks in Projections
When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows:
f { a : 22 b { d : 1 x : 2 } y : 13 } z: 8
The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output):
f { a : 22 b { d : 1 } }
A repeated field is not allowed except at the last position of a paths string.
If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified).
Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs.
Field Masks in Update Operations
A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask.
If a repeated field is specified for an update operation, new values will
be appended to the existing repeated field in the target resource. Note that
a repeated field is only allowed in the last position of a paths string.
If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource.
For example, given the target message:
f { b { d: 1 x: 2 } c: [1] }
And an update message:
f { b { d: 10 } c: [2] }
then if the field mask is:
paths: ["f.b", "f.c"]
then the result will be:
f { b { d: 10 x: 2 } c: [1, 2] }
An implementation may provide options to override this default behavior for repeated and message fields.
In order to reset a field's value to the default, the field must be in the mask and set to the default value in the provided resource. Hence, in order to reset all fields of a resource, provide a default instance of the resource and set all fields in the mask, or do not provide a mask as described below.
If a field mask is not present on update, the operation applies to all fields (as if a field mask of all fields has been specified). Note that in the presence of schema evolution, this may mean that fields the client does not know and has therefore not filled into the request will be reset to their default. If this is unwanted behavior, a specific service may require a client to always specify a field mask, producing an error if not.
As with get operations, the location of the resource which describes the updated values in the request message depends on the operation kind. In any case, the effect of the field mask is required to be honored by the API.
Considerations for HTTP REST
The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates).
JSON Encoding of Field Masks
In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions.
As an example, consider the following message declarations:
message Profile { User user = 1; Photo photo = 2; } message User { string display_name = 1; string address = 2; }
In proto a field mask for Profile may look as such:
mask { paths: "user.display_name" paths: "photo" }
In JSON, the same mask is represented as below:
{ mask: "user.displayName,photo" }
Field Masks and Oneof Fields
Field masks treat fields in oneofs just as regular fields. Consider the following message:
message SampleMessage { oneof test_oneof { string name = 4; SubMessage sub_message = 9; } }
The field mask can be:
mask { paths: "name" }
Or:
mask { paths: "sub_message" }
Note that oneof type names ("test_oneof" in this case) cannot be used in paths.
Field Mask Verification
The implementation of any API method which has a FieldMask type field in the
request should verify the included field paths, and return an
INVALID_ARGUMENT error if any path is unmappable.
google/protobuf/empty.proto
Messages
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);
}
google/rpc/status.proto
Messages
The Status type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by gRPC. Each Status message contains
three pieces of data: error code, error message, and error details.
You can find out more about this error model and how to work with it in the API Design Guide.
google/rpc/error_details.proto
Messages
Describes violations in a client request. This error type focuses on the syntactic aspects of the request.
A message type used to describe a single bad request field.
text,json message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } optional string email = 1; repeated EmailType type = 2; } string full_name = 1; repeated EmailAddress email_addresses = 2; } In this example, in proto field could take one of the following values: * full_name for a violation in the full_name value * email_addresses[1].email for a violation in the email field of the first email_addresses message * email_addresses[3].type[2] for a violation in the second type value in the third email_addresses message. In JSON, the same values are represented as: * fullName for a violation in the fullName value * emailAddresses[1].email for a violation in the email field of the first emailAddresses message * emailAddresses[3].type[2] for a violation in the second type value in the third emailAddresses message.[A-Z][A-Z0-9_]+[A-Z0-9], which represents UPPER_SNAKE_CASE.Describes additional debugging info.
Describes the cause of the error with structured details.
Example of an error when contacting the "pubsub.googleapis.com" API when it is not enabled:
{ "reason": "API_DISABLED"
"domain": "googleapis.com"
"metadata": {
"resource": "projects/123",
"service": "pubsub.googleapis.com"
}
}
This response indicates that the pubsub.googleapis.com API is not enabled.
Example of an error that is returned when attempting to create a Spanner instance in a region that is out of stock:
{ "reason": "STOCKOUT"
"domain": "spanner.googleapis.com",
"metadata": {
"availableRegions": "us-central1,us-east2"
}
}
[a-z][a-zA-Z0-9-_]+ but should ideally be lowerCamelCase. Also, they must be limited to 64 characters in length. When identifying the current value of an exceeded limit, the units should be contained in the key, not the value. For example, rather than {"instanceLimit": "100/request"}, should be returned as, {"instanceLimitPerRequest": "100"}, if the client exceeds the number of instances that can be created in a single (batch) request.[A-Z][A-Z0-9_]+[A-Z0-9], which represents UPPER_SNAKE_CASE.Provides links to documentation or for performing an out of band action.
For example, if a quota check failed with an error indicating the calling project hasn't enabled the accessed service, this can contain a URL pointing directly to the right place in the developer console to flip the bit.
Describes a URL link.
Provides a localized error message that is safe to return to the user which can be attached to an RPC error.
Describes what preconditions have failed.
For example, if an RPC failed because it required the Terms of Service to be acknowledged, it could list the terms of service violation in the PreconditionFailure message.
A message type used to describe a single precondition failure.
Describes how a quota check failed.
For example if a daily limit was exceeded for the calling project,
a service could respond with a QuotaFailure detail containing the project
id and the description of the quota limit that was exceeded. If the
calling project hasn't enabled the service in the developer console, then
a service could respond with the project id and set service_disabled
to true.
Also see RetryInfo and Help types for other details about handling a quota failure.
A message type used to describe a single quota violation. For example, a daily quota or a custom quota that was exceeded.
clientip:<ip address of client> or project:<Google developer project id>.Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback.
Describes the resource that is being accessed.
writer permission on the developer console project.user:<owner email> or project:<Google developer project id>.Describes when the clients can retry a failed request. Clients could ignore the recommendation here or retry when this information is missing from error responses.
It's always recommended that clients should use exponential backoff when retrying.
Clients should wait until retry_delay amount of time has passed since
receiving the error response before retrying. If retrying requests also
fail, clients should use an exponential backoff scheme to gradually increase
the delay between retries based on retry_delay, until either a maximum
number of retries have been reached or a maximum retry delay cap has been
reached.
Scalar Value Types
double
float
int32
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.
int64
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.
uint32
Uses variable-length encoding.
uint64
Uses variable-length encoding.
sint32
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.
sint64
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.
fixed32
Always four bytes. More efficient than uint32 if values are often greater than 2^28.
fixed64
Always eight bytes. More efficient than uint64 if values are often greater than 2^56.
sfixed32
Always four bytes.
sfixed64
Always eight bytes.
bool
string
A string must always contain UTF-8 encoded or 7-bit ASCII text.
bytes
May contain any arbitrary sequence of bytes.