Files
memos/proto/api/attachment_service.proto
T

378 lines
14 KiB
Protocol Buffer

syntax = "proto3";
package memos.api;
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
option go_package = "gen/api";
// AttachmentService manages files attached to memos.
service AttachmentService {
// ListAttachments lists attachments linked to memos the caller can read, plus the caller's unlinked uploads.
rpc ListAttachments(ListAttachmentsRequest) returns (ListAttachmentsResponse) {
option (google.api.http) = {get: "/api/attachments"};
}
// GetAttachment gets an attachment by name. An unlinked attachment is visible only to its uploader and admins;
// a linked attachment follows the read access of its memo.
rpc GetAttachment(GetAttachmentRequest) returns (Attachment) {
option (google.api.http) = {get: "/api/{name=attachments/*}"};
option (google.api.method_signature) = "name";
}
// CreateAttachment creates an attachment from inline content.
rpc CreateAttachment(CreateAttachmentRequest) returns (Attachment) {
option (google.api.http) = {
post: "/api/attachments"
body: "attachment"
};
option (google.api.method_signature) = "attachment";
}
// UpdateAttachment updates an attachment. Only `filename` can be updated. The caller must be the uploader or an
// admin.
rpc UpdateAttachment(UpdateAttachmentRequest) returns (Attachment) {
option (google.api.http) = {
patch: "/api/{attachment.name=attachments/*}"
body: "attachment"
};
option (google.api.method_signature) = "attachment,update_mask";
}
// DeleteAttachment deletes an attachment uploaded by the caller.
rpc DeleteAttachment(DeleteAttachmentRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {delete: "/api/{name=attachments/*}"};
option (google.api.method_signature) = "name";
}
// BatchDeleteAttachments deletes up to 100 attachments in one atomic request. The caller must be the uploader of
// each attachment or an admin.
rpc BatchDeleteAttachments(BatchDeleteAttachmentsRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/api/attachments:batchDelete"
body: "*"
};
}
// UploadAttachment uploads a file in bounded chunks. The first call carries the spec and returns an upload_id;
// later calls carry that upload_id. Uploads are bound to the authenticated user, expire after 30 minutes of
// inactivity, and do not survive a server restart.
rpc UploadAttachment(UploadAttachmentRequest) returns (UploadAttachmentResponse) {
option (google.api.http) = {
post: "/api/attachments:upload"
body: "*"
};
}
}
// Attachment is a file uploaded by a user, optionally linked to a memo.
message Attachment {
option (google.api.resource) = {
type: "memos.api/Attachment"
pattern: "attachments/{attachment}"
singular: "attachment"
plural: "attachments"
};
// Identifier. The resource name of the attachment.
// Format: attachments/{attachment}
string name = 1 [(google.api.field_behavior) = IDENTIFIER];
// Output only. The user who uploaded the attachment, which may differ from the creator of the linked memo.
// Format: users/{user}
string creator = 2 [
(google.api.field_behavior) = OUTPUT_ONLY,
(google.api.resource_reference) = {type: "memos.api/User"}
];
// Required. The filename of the attachment.
string filename = 3 [(google.api.field_behavior) = REQUIRED];
// Required. The MIME type of the attachment. If empty on create, the service detects it from the filename and
// content.
string type = 4 [(google.api.field_behavior) = REQUIRED];
// Input only. The content of the attachment.
bytes content = 5 [(google.api.field_behavior) = INPUT_ONLY];
// Optional. The external link of the attachment. Set only for externally stored attachments; ignored on create.
string external_link = 6 [(google.api.field_behavior) = OPTIONAL];
// Optional. Motion photo metadata. Clients may only supply Apple Live Photo metadata; the service detects Android
// motion photos in JPEG content.
MotionMedia motion_media = 7 [(google.api.field_behavior) = OPTIONAL];
// Optional. Normalized media metadata supplied by the client at creation time. Immutable after creation.
MediaMetadata media_metadata = 8 [
(google.api.field_behavior) = OPTIONAL,
(google.api.field_behavior) = IMMUTABLE
];
// Optional. The memo the attachment is linked to. On create, the caller must be able to manage the memo.
// Format: memos/{memo}
optional string memo = 9 [(google.api.field_behavior) = OPTIONAL];
// Output only. The size of the stored content in bytes.
int64 size = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. The creation time.
google.protobuf.Timestamp create_time = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
}
// Request message for AttachmentService.ListAttachments.
message ListAttachmentsRequest {
// Optional. The maximum number of attachments to return. The service may return fewer.
// If unspecified, at most 50 attachments are returned. Values above 1000 are coerced to 1000.
int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];
// Optional. A page token from a previous call. Provide it to retrieve the next page.
string page_token = 2 [(google.api.field_behavior) = OPTIONAL];
// Optional. A CEL filter over the results.
// Example: `mime_type == "image/png"` or `filename.contains("test")`.
// Supported operators: ==, !=, <, <=, >, >=, : (contains), in.
// Supported fields: creator, filename, mime_type, create_time, memo_id, space.
// `creator` is the linked memo's creator, or the uploader for an unlinked attachment. It supports equality with a
// User resource name.
// `space` is the linked memo's Space resource name, or null when the attachment is unlinked or its memo has no
// space. It supports only a non-negated `==` comparison with a Space resource name or null.
string filter = 3 [(google.api.field_behavior) = OPTIONAL];
// Optional. The order to sort results by, such as "create_time desc" or "filename asc". The service does not apply
// it yet.
string order_by = 4 [(google.api.field_behavior) = OPTIONAL];
}
// Response message for AttachmentService.ListAttachments.
message ListAttachmentsResponse {
// The attachments.
repeated Attachment attachments = 1;
// A token to retrieve the next page. Empty when there are no more pages.
string next_page_token = 2;
}
// Request message for AttachmentService.GetAttachment.
message GetAttachmentRequest {
// Required. The name of the attachment to get.
// Format: attachments/{attachment}
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "memos.api/Attachment"}
];
}
// Request message for AttachmentService.CreateAttachment.
message CreateAttachmentRequest {
// Required. The attachment to create.
Attachment attachment = 1 [(google.api.field_behavior) = REQUIRED];
// Optional. The ID to use for the attachment. If empty, a unique ID is generated.
// Format: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$
string attachment_id = 2 [(google.api.field_behavior) = OPTIONAL];
}
// Request message for AttachmentService.UpdateAttachment.
message UpdateAttachmentRequest {
// Required. The attachment to update. Its `name` identifies the attachment.
Attachment attachment = 1 [(google.api.field_behavior) = REQUIRED];
// Required. The fields to update. Only `filename` is supported.
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}
// Request message for AttachmentService.DeleteAttachment.
message DeleteAttachmentRequest {
// Required. The name of the attachment to delete.
// Format: attachments/{attachment}
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "memos.api/Attachment"}
];
}
// Request message for AttachmentService.BatchDeleteAttachments.
message BatchDeleteAttachmentsRequest {
// Required. The names of the attachments to delete, at most 100. Duplicate names are ignored.
// Format: attachments/{attachment}
repeated string names = 1 [(google.api.field_behavior) = REQUIRED];
}
// Request message for AttachmentService.UploadAttachment.
message UploadAttachmentRequest {
// Starts a new upload or continues an existing one. Exactly one must be set.
oneof upload {
// Starts a new upload. The same call may also carry data and finish_write.
UploadAttachmentSpec spec = 1;
// Continues the upload identified by a previous response.
string upload_id = 2;
}
// Required. Zero-based byte offset at which data is written. Must equal the committed size, except when retrying
// the most recently accepted chunk with identical bytes and offset, which is accepted without writing again.
int64 write_offset = 3 [(google.api.field_behavior) = REQUIRED];
// Optional. File bytes, at most max_chunk_size long. With no data and finish_write false, the call reports
// progress without writing, and write_offset is ignored.
bytes data = 4 [(google.api.field_behavior) = OPTIONAL];
// Optional. Finalize the upload after writing data. The committed size must then equal total_size. Any later call
// for the same upload_id returns the created attachment.
bool finish_write = 5 [(google.api.field_behavior) = OPTIONAL];
}
// Response message for AttachmentService.UploadAttachment.
message UploadAttachmentResponse {
// Opaque ID for subsequent calls. This is not a resource name.
string upload_id = 1;
// Number of file bytes committed so far.
int64 committed_size = 2;
// Maximum number of data bytes accepted in one call.
int32 max_chunk_size = 3;
// The created attachment. Set once the upload has been finalized.
Attachment attachment = 4;
}
// UploadAttachmentSpec describes the attachment that a new upload creates.
message UploadAttachmentSpec {
// Required. Metadata for the attachment to create. content must be empty; file bytes are sent in data.
Attachment attachment = 1 [(google.api.field_behavior) = REQUIRED];
// Optional. The ID to use for the attachment. If empty, a unique ID is generated.
// Format: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$
string attachment_id = 2 [(google.api.field_behavior) = OPTIONAL];
// Optional. Total size of the file in bytes before media processing. Zero represents an empty file.
int64 total_size = 3 [(google.api.field_behavior) = OPTIONAL];
}
// MotionMedia links the parts of a motion photo.
message MotionMedia {
// The motion photo format.
MotionMediaFamily family = 1;
// The part this attachment plays in the motion photo.
MotionMediaRole role = 2;
// Groups the attachments that belong to one motion photo. Required for client-supplied Apple Live Photo metadata;
// for an Android motion photo it is the attachment's own ID.
string group_id = 3;
// Presentation timestamp of the still frame within the video, in microseconds.
int64 presentation_timestamp_us = 4;
// Whether the file embeds the motion video, as in an Android motion photo container.
bool has_embedded_video = 5;
}
// MotionMediaFamily is the format of a motion photo.
enum MotionMediaFamily {
MOTION_MEDIA_FAMILY_UNSPECIFIED = 0;
// An Apple Live Photo: a still image and a video stored as separate attachments.
APPLE_LIVE_PHOTO = 1;
// An Android motion photo: a JPEG with an embedded video.
ANDROID_MOTION_PHOTO = 2;
}
// MotionMediaRole is the part an attachment plays in a motion photo.
enum MotionMediaRole {
MOTION_MEDIA_ROLE_UNSPECIFIED = 0;
// The still image of an Apple Live Photo.
STILL = 1;
// The video of an Apple Live Photo.
VIDEO = 2;
// A single file holding both the still image and the video.
CONTAINER = 3;
}
// MediaMetadata contains normalized metadata explicitly supplied by a client.
// The service validates and stores this data but does not extract it from the media file.
message MediaMetadata {
// Display-oriented width in pixels. Must be provided with height.
optional int32 width = 1;
// Display-oriented height in pixels. Must be provided with width.
optional int32 height = 2;
// Type-specific metadata. Must match the attachment's MIME type.
oneof details {
// Photo metadata, for image attachments.
PhotoMetadata photo = 3;
// Video metadata, for video attachments.
VideoMetadata video = 4;
}
}
// PhotoMetadata is metadata recorded by the source of a photo.
message PhotoMetadata {
// Capture time as recorded by the source media.
MediaCaptureTime capture_time = 1;
// Geographic location recorded by the source media.
MediaLocation location = 2;
// EXIF orientation value from 1 through 8 as recorded by the source file.
// This value is informational and must not be reapplied to the stored attachment;
// width and height already describe its display-oriented dimensions.
optional int32 source_exif_orientation = 3;
// The camera manufacturer.
string camera_make = 4;
// The camera model.
string camera_model = 5;
// The lens model.
string lens_model = 6;
// The aperture f-number.
optional double f_number = 7;
// The exposure time in seconds.
optional double exposure_time_seconds = 8;
// The ISO sensitivity.
optional int32 iso = 9;
// The focal length in millimeters.
optional double focal_length_mm = 10;
}
// MediaCaptureTime is the local time at which media was captured.
message MediaCaptureTime {
// Local date and time without a time zone, formatted as YYYY-MM-DDTHH:mm:ss[.fraction].
string local_date_time = 1;
// UTC offset formatted as Z or +/-HH:MM.
optional string utc_offset = 2;
}
// MediaLocation is the geographic location at which media was captured.
message MediaLocation {
// WGS84 latitude in decimal degrees. Must be provided with longitude.
optional double latitude = 1;
// WGS84 longitude in decimal degrees. Must be provided with latitude.
optional double longitude = 2;
// Signed altitude in meters relative to sea level.
optional double altitude_meters = 3;
}
// VideoMetadata is metadata recorded by the source of a video.
message VideoMetadata {
// The duration of the video in seconds.
optional double duration_seconds = 1;
}