diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 5b4e643f1d..22f40d575c 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -6,8 +6,10 @@ .. rest_expand_all:: -.. include:: storage-account-services.inc -.. include:: storage_endpoints.inc -.. include:: storage-object-services.inc -.. include:: storage-container-services.inc .. include:: storage_info.inc +.. include:: storage-account-services.inc +.. include:: storage-container-services.inc +.. include:: storage-object-services.inc +.. include:: storage_endpoints.inc + + diff --git a/api-ref/source/metadata_header_encoding.inc b/api-ref/source/metadata_header_encoding.inc new file mode 100644 index 0000000000..f10ae806a0 --- /dev/null +++ b/api-ref/source/metadata_header_encoding.inc @@ -0,0 +1,4 @@ +The metadata value must be UTF-8-encoded and then +URL-encoded before you include it in the header. +This is a direct violation of the HTTP/1.1 `basic rules +`_. diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 28e7a93e4c..d4c79e8e4d 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -22,9 +22,9 @@ Content-Disposition: in: header required: false type: string -Content-Disposition_1: +Content-Disposition_resp: description: | - If set, specifies the override behavior for the + If present, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default. If not set, this header is not @@ -39,37 +39,36 @@ Content-Encoding: in: header required: false type: string -Content-Encoding_1: +Content-Encoding_resp: description: | - If set, the value of the ``Content-Encoding`` + If present, the value of the ``Content-Encoding`` metadata. If not set, the operation does not return this header. in: header required: false type: string -Content-Length: +Content-Length_cud_resp: description: | If the operation succeeds, this value is zero - (0). If the operation fails, this value is the length of the error + (0) or the length of informational or error text in the response body. in: header required: true type: string -Content-Length_1: +Content-Length_get_resp: description: | - Set to the length of the object content. Do not - set if chunked transfer encoding is being used. - in: header - required: false - type: integer -Content-Length_2: - description: | - The length of the response body that contains the - list of names. If the operation fails, this value is the length of - the error text in the response body. + The length of the object content in the response + body, in bytes. in: header required: true type: string -Content-Length_3: +Content-Length_listing_resp: + description: | + If the operation succeeds, the length of the response body + in bytes. On error, this is the length of the error text. + in: header + required: true + type: string +Content-Length_obj_head_resp: description: | HEAD operations do not return content. The ``Content-Length`` header value is not the size of the response @@ -77,33 +76,22 @@ Content-Length_3: in: header required: true type: string -Content-Length_4: +Content-Length_put_req: description: | - The length of the object content in the response - body, in bytes. + Set to the length of the object content (i.e. the length in bytes + of the request body). Do not + set if chunked transfer encoding is being used. in: header - required: true - type: string -Content-Type: + required: false + type: integer +Content-Type_cud_resp: description: | - Changes the MIME type for the object. + If present, this value is the MIME + type of the informational or error text in the response body. in: header required: false type: string -Content-Type_1: - description: | - If the operation fails, this value is the MIME - type of the error text in the response body. - in: header - required: true - type: string -Content-Type_2: - description: | - The MIME type of the object. - in: header - required: true - type: string -Content-Type_3: +Content-Type_listing_resp: description: | The MIME type of the list of names. If the operation fails, this value is the MIME type of the error text in @@ -111,23 +99,25 @@ Content-Type_3: in: header required: true type: string +Content-Type_obj_cu_req: + description: | + Sets the MIME type for the object. + in: header + required: false + type: string +Content-Type_obj_resp: + description: | + The MIME type of the object. + in: header + required: true + type: string Date: description: | - The transaction date and time. - - The date and time stamp format is `ISO 8601 - `_: - - :: - - CCYY-MM-DDThh:mm:ss±hh:mm - - For example, ``2015-08-27T09:49:58-05:00``. - - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. In the previous example, the offset value is ``-05:00``. - - A ``null`` value indicates that the token never expires. + The date and time the system responded to the request, + using the preferred format of + `RFC 7231 `_ as + shown in this example ``Thu, 16 Jun 2016 15:10:38 GMT``. The time is + always in UTC. in: header required: true type: string @@ -140,14 +130,29 @@ Destination: in: header required: true type: string -ETag: +Destination-Account: + description: | + Specifies the account name where the object is copied to. If not + specified, the object is copied to the account which owns the object + (i.e., the account in the path). + in: header + required: false + type: string +ETag_obj_copied: description: | The MD5 checksum of the copied object content. The value is not quoted. in: header required: true type: string -ETag_1: +ETag_obj_received: + description: | + The MD5 checksum of the uploaded object content. + The value is not quoted. + in: header + required: true + type: string +ETag_obj_req: description: | The MD5 checksum value of the request body. For example, the MD5 checksum value of the object content. You are @@ -158,7 +163,7 @@ ETag_1: in: header required: false type: string -ETag_2: +ETag_obj_resp: description: | For objects smaller than 5 GB, this value is the MD5 checksum of the object content. The value is not quoted. For @@ -190,7 +195,7 @@ If-Modified-Since: If-None-Match: description: | In combination with ``Expect: 100-Continue``, - specify an ``"If- None-Match: *"`` header to query whether the + specify an ``"If-None-Match: *"`` header to query whether the server already has a copy of the object before any data is sent. in: header required: false @@ -205,19 +210,10 @@ If-Unmodified-Since: Last-Modified: description: | The date and time when the object was created or its metadata was - changed. + changed. The date and time is formaatted as shown in this + example: ``Fri, 12 Aug 2016 14:24:16 GMT`` - The date and time stamp format is `ISO 8601 - `_: - - :: - - CCYY-MM-DDThh:mm:ss±hh:mm - - For example, ``2015-08-27T09:49:58-05:00``. - - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. In the previous example, the offset value is ``-05:00``. + The time is always in UTC. in: header required: true type: string @@ -233,18 +229,21 @@ Range: do, the value defaults to the offset of the last byte of data. - **Suffix byte range specification**. Use LENGTH bytes to specify the length of the data range. The following forms of the header - specify the following ranges of data: - ``Range: bytes=-5``. The - last five bytes. - ``Range: bytes=10-15``. The six bytes of data - after a 10-byte offset. - ``Range: bytes=10-15,-5``. A multi- - part response that contains the last five bytes and the six - bytes of data after a 10-byte offset. The ``Content-Type`` - response header contains ``multipart/byteranges``. - ``Range: - bytes=4-6``. Bytes 4 to 6 inclusive. - ``Range: bytes=2-2``. Byte - 2, the third byte of the data. - ``Range: bytes=6-``. Byte 6 and - after. - ``Range: bytes=1-3,2-5``. A multi-part response that - contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The - ``Content-Type`` response header contains - ``multipart/byteranges``. + specify the following ranges of data: + + - ``Range: bytes=-5``. The last five bytes. + - ``Range: bytes=10-15``. The six bytes of data after a 10-byte offset. + - ``Range: bytes=10-15,-5``. A multi-part response that contains the + last five bytes and the six + bytes of data after a 10-byte offset. The ``Content-Type`` + response header contains ``multipart/byteranges``. + - ``Range: bytes=4-6``. Bytes 4 to 6 inclusive. + - ``Range: bytes=2-2``. Byte 2, the third byte of the data. + - ``Range: bytes=6-``. Byte 6 and after. + - ``Range: bytes=1-3,2-5``. A multi-part response that + contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The + ``Content-Type`` response header contains + ``multipart/byteranges``. in: header required: false type: string @@ -272,23 +271,31 @@ X-Account-Container-Count: X-Account-Meta-name: description: | The custom account metadata item, where - ``{name}`` is the name of the metadata item. One ``X-Account- - Meta- {name}`` response header appears for each metadata item (for - each ``{name}``). + ``name`` is the name of the metadata item. One ``X-Account-Meta-name`` + response header appears for each metadata item (for + each ``name``). in: header required: false type: string -X-Account-Meta-name_1: +X-Account-Meta-name_req: description: | - The account metadata. The ``{name}`` is the name + The account metadata. The ``name`` is the name of metadata item that you want to add, update, or delete. To delete this item, send an empty value in this header. You must - specify an ``X-Account-Meta- {name}`` header for each metadata - item (for each ``{name}``) that you want to add, update, or + specify an ``X-Account-Meta-name`` header for each metadata + item (for each ``name``) that you want to add, update, or delete. in: header required: false type: string +X-Account-Meta-Quota-Bytes_resp: + description: | + If present, this is the limit on the total size in bytes of objects stored + in the account. + Typically this value is set by an administrator. + in: header + required: false + type: string X-Account-Meta-Temp-URL-Key: description: | The secret key value for temporary URLs. If not @@ -311,6 +318,28 @@ X-Account-Object-Count: in: header required: true type: integer +X-Account-Storage-Policy-name-Bytes-Used: + description: | + The total number of bytes that are stored in + in a given storage policy, where ``name`` is the + name of the storage policy. + in: header + required: true + type: integer +X-Account-Storage-Policy-name-Container-Count: + description: | + The number of containers in the account that use the given + storage policy where ``name`` is the name of the storage policy. + in: header + required: true + type: integer +X-Account-Storage-Policy-name-Object-Count: + description: | + The number of objects in given storage policy where ``name`` is + the name of the storage policy. + in: header + required: true + type: integer X-Auth-Token: description: | Authentication token. If you omit this header, @@ -319,12 +348,6 @@ X-Auth-Token: in: header required: false type: string -X-Auth-Token_1: - description: | - Authentication token. - in: header - required: true - type: string X-Container-Bytes-Used: description: | The total number of bytes used. @@ -359,9 +382,9 @@ X-Container-Meta-Access-Control-Expose-Headers: `http://www.w3.org/TR/cors/#simple-response-header `_. - The headers ``etag``, ``x-timestamp``, ``x-trans-id``. - All metadata - headers (``X-Container-Meta-*`` for containers and ``X-Object- - Meta-*`` for objects) headers listed in ``X-Container- Meta- - Access-Control-Expose-Headers``. + headers (``X-Container-Meta-*`` for containers and + ``X-Object-Meta-*`` for objects) headers listed in + ``X-Container-Meta-Access-Control-Expose-Headers``. in: header required: false type: string @@ -376,28 +399,32 @@ X-Container-Meta-Access-Control-Max-Age: type: string X-Container-Meta-name: description: | - The container metadata, where ``{name}`` is the - name of metadata item. You must specify an ``X-Container-Meta- - {name}`` header for each metadata item (for each ``{name}``) that + The custom container metadata item, where + ``name`` is the name of the metadata item. One ``X-Container-Meta-name`` + response header appears for each metadata item (for + each ``name``). + in: header + required: true + type: string +X-Container-Meta-name_req: + description: | + The container metadata, where ``name`` is the + name of metadata item. You must specify an ``X-Container-Meta-name`` + header for each metadata item (for each ``name``) that you want to add or update. in: header required: false type: string -X-Container-Meta-name_1: - description: | - The custom container metadata item, where - ``{name}`` is the name of the metadata item. One ``X-Container- - Meta- {name}`` response header appears for each metadata item (for - each ``{name}``). - in: header - required: true - type: string X-Container-Meta-Quota-Bytes: description: | Sets maximum size of the container, in bytes. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value. + This value does not take effect immediately. see + `Container Quotas + `_ + for more information. in: header required: false type: string @@ -407,6 +434,10 @@ X-Container-Meta-Quota-Count: Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value. + This value does not take effect immediately. see + `Container Quotas + `_ + for more information. in: header required: false type: string @@ -431,7 +462,7 @@ X-Container-Meta-Web-Directory-Type: ``application/directory``. Directory marker objects are 0-byte objects that represent directories to create a simulated hierarchical structure. For example, if you set ``"X-Container- - Meta-Web-Directory- Type: text/directory"``, Object Storage treats + Meta-Web-Directory-Type: text/directory"``, Object Storage treats 0-byte objects with a content-type of ``text/directory`` as directories rather than objects. in: header @@ -446,47 +477,18 @@ X-Container-Object-Count: X-Container-Read: description: | Sets a container access control list (ACL) that grants read access. - Container ACLs are available on any Object Storage cluster, and are - enabled by container rather than by cluster. + The scope of the access is specific to the container. The ACL grants + the ability to perform GET or HEAD operations on objects in the container + or to perform a GET or HEAD operation on the container itself. - To set the container read ACL: - - .. code-block:: bash - - $ curl -X {PUT|POST} -i -H "X-Auth-Token: TOKEN" -H \ - "X-Container-Read: ACL" STORAGE_URL/CONTAINER - - For example: - - .. code-block:: bash - - $ curl -X PUT -i \ - -H "X-Auth-Token: 0101010101" \ - -H "X-Container-Read: .r:*" \ - http://swift.example.com/v1/AUTH_bob/read_container - - In the command, specify the ACL in the ``X-Container-Read`` header, - as follows: - - - ``.r:*`` All referrers. - - - ``.r:example.com,swift.example.com`` Comma-separated list of - referrers. - - - ``.rlistings`` Container listing access. - - - ``AUTH_username`` Access to a user who authenticates through a - legacy or non-OpenStack-Identity-based authentication system. - - - ``LDAP_`` Access to all users who authenticate through an LDAP- - based legacy or non-OpenStack-Identity-based authentication - system. + The format and scope of the ACL is dependent on the authorization system + used by the Object Storage service. in: header required: false type: string -X-Container-Read_1: +X-Container-Read_resp: description: | - The ACL that grants read access. If not set, this + The ACL that grants read access. If there is no ACL, this header is not returned by this operation. in: header required: false @@ -496,10 +498,13 @@ X-Container-Sync-Key: Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted. + For more information, see `Container to Container Synchronization + `_ in: header required: false type: string -X-Container-Sync-Key_1: +X-Container-Sync-Key_resp: description: | The secret key for container synchronization. If not set, this header is not returned by this operation. @@ -516,7 +521,7 @@ X-Container-Sync-To: in: header required: false type: string -X-Container-Sync-To_1: +X-Container-Sync-To_resp: description: | The destination for container synchronization. If not set, this header is not returned by this operation. @@ -525,13 +530,21 @@ X-Container-Sync-To_1: type: string X-Container-Write: description: | - Sets an ACL that grants write access. + Sets a container access control list (ACL) that grants write access. + The scope of the access is specific to the container. The ACL grants + the ability to perform PUT, POST and DELETE operations on + objects in the container. It does not grant write access to the container + metadata. + + The format of the ACL is dependent on the authorization system + used by the Object Storage service. + in: header required: false type: string -X-Container-Write_1: - description: | - The ACL that grants write access. If not set, +X-Container-Write_resp: + description: + The ACL that grants write access. If there is no ACL, this header is not returned by this operation. in: header required: false @@ -544,6 +557,13 @@ X-Copied-From: in: header required: false type: string +X-Copied-From-Account: + description: | + For a copied object, shows the account + from which the new object was copied. + in: header + required: false + type: string X-Copied-From-Last-Modified: description: | For a copied object, the date and time in `UNIX @@ -572,7 +592,7 @@ X-Delete-After: description: | The number of seconds after which the system removes the object. Internally, the Object Storage system stores - this value in the ``X -Delete-At`` metadata item. + this value in the ``X-Delete-At`` metadata item. in: header required: false type: integer @@ -585,21 +605,11 @@ X-Delete-At: in: header required: false type: integer -X-Delete-At_1: - description: | - If set, the date and time in `UNIX Epoch time - stamp format `_ when the - system deletes the object. For example, ``1440619048`` is - equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. If not set, - this operation does not return this header. - in: header - required: false - type: integer X-Detect-Content-Type: description: | If set to ``true``, Object Storage guesses the content type based on the file extension and ignores the value - sent in the ``Content- Type`` header, if present. + sent in the ``Content-Type`` header, if present. in: header required: false type: boolean @@ -631,9 +641,9 @@ X-Object-Manifest: in: header required: false type: string -X-Object-Manifest_1: +X-Object-Manifest_resp: description: | - If set, to this is a dynamic large object + If present, this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form ``container/prefix``. in: header @@ -641,26 +651,35 @@ X-Object-Manifest_1: type: string X-Object-Meta-name: description: | - The object metadata, where ``{name}`` is the name - of the metadata item. You must specify an ``X-Object-Meta- - {name}`` header for each metadata ``{name}`` item that you want to - add or update. + The object metadata, where ``name`` is the name + of the metadata item. You must specify an + ``X-Object-Meta-name`` header for each metadata ``name`` item that + you want to add or update. in: header required: false type: string -X-Object-Meta-name_1: +X-Object-Meta-name_resp: description: | - The custom object metadata item, where ``{name}`` - is the name of the metadata item. One ``X-Object-Meta- {name}`` - response header appears for each metadata ``{name}`` item. + If present, the custom object metadata item, where ``name`` + is the name of the metadata item. One``X-Object-Meta-name`` + response header appears for each metadata ``name`` item. in: header - required: true + required: false + type: string +X-Remove-Account-name: + description: | + Removes the metadata item named ``name``. + For example, ``X-Remove-Account-Meta-Blue`` removes + custom metadata. + in: header + required: false type: string X-Remove-Container-name: description: | - Removes the metadata item named ``{name}``. For - example, ``X -Remove-Container-Read`` removes the ``X-Container- - Read`` metadata item. + Removes the metadata item named ``name``. For + example, ``X-Remove-Container-Read`` removes the + ``X-Container-Read`` metadata item and ``X-Remove-Container-Meta-Blue`` + removes custom metadata. in: header required: false type: string @@ -670,6 +689,14 @@ X-Remove-Versions-Location: in: header required: false type: string +X-Service-Token: + description: | + A service token. See `OpenStack Service Using Composite Tokens + `_ for more information. + in: header + required: false + type: string X-Static-Large-Object: description: | Set to ``true`` if this object is a static large @@ -677,6 +704,14 @@ X-Static-Large-Object: in: header required: true type: boolean +X-Storage-Policy: + description: | + In requests, specifies the name of the storage policy to use for + the container. In responses, is the storage policy name. + The storage policy of the container cannot be changed. + in: header + required: false + type: string X-Timestamp: description: | The date and time in `UNIX Epoch time stamp @@ -696,23 +731,23 @@ X-Trans-Id: type: string X-Trans-Id-Extra: description: | - Extra transaction information. Use the ``X-Trans- - Id-Extra`` request header to include extra information to help you + Extra transaction information. Use the ``X-Trans-Id-Extra`` + request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the - first 32 characters of the ``X-Trans-Id- Extra`` request header + first 32 characters of the ``X-Trans-Id-Extra`` request header value to the transaction ID value in the generated ``X-Trans-Id`` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the ``X -Trans-Id-Extra`` request header. For example, you can include extra transaction information when you upload `large objects - `_ such as images. When + `_ + such as images. When you upload each segment and the manifest, include the same value in the ``X-Trans-Id-Extra`` request header. If an error occurs, you can find all requests that are related to the large object - upload in the Object Storage logs. You can also use ``X-Trans-Id- - Extra`` strings to help operators debug requests that fail to + upload in the Object Storage logs. You can also use ``X-Trans-Id-Extra`` + strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs. in: header @@ -728,6 +763,16 @@ X-Versions-Location: in: header required: false type: string +X-Versions-Location_resp: + description: | + If present, this container has versioning enabled and the value + is the UTF-8 encoded name of another container. + For more information about object versioning, + see `Object versioning `_. + in: header + required: false + type: string X-Versions-Mode: description: | The versioning mode for this container. The value must be either @@ -739,6 +784,15 @@ X-Versions-Mode: in: header required: false type: string +X-Versions-Mode_resp: + description: | + If set, this is the versioning mode for this container. The value is either + ``stack`` or ``history``. For more information about object versioning, + see `Object versioning `_. + in: header + required: false + type: string # variables in path account: @@ -750,12 +804,13 @@ account: type: string container: description: | - The unique name for the container. The container + The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (``/``) character because this character delimits the container and object name. For - example, ``/account/container/object``. + example, the path ``/v1/account/www/pages`` specifies the ``www`` + container, not the ``www/pages`` container. in: path required: false type: string @@ -767,6 +822,16 @@ object: type: string # variables in query +bulk-delete: + description: | + When the ``bulk-delete`` query parameter is present in the POST + request, multiple objects or containers can be deleted + with a single request. See `Bulk Delete + `_ for how this feature is used. + in: query + required: false + type: string delimiter: description: | Delimiter value, which returns the object names @@ -784,6 +849,16 @@ end_marker: in: query required: false type: string +extract-archive: + description: | + When the ``extract-archive`` query parameter is present in the POST + request, an archive (tar file) is uploaded and extracted to + create multiple objects. See `Extract Archive + `_ for how this feature is used. + in: query + required: false + type: string filename: description: | Overrides the default file name. Object Storage @@ -823,23 +898,24 @@ marker: in: query required: false type: string -multipart-manifest: +multipart-manifest_copy: description: | - If ``?multipart-manifest=put``, the object is a - static large object manifest and the body contains the manifest. + If you include the ``multipart-manifest=get`` + query parameter and the object is a large object, the object + contents are not copied. Instead, the manifest is copied to + the new object. in: query required: false type: string -multipart-manifest_1: +multipart-manifest_delete: description: | If you include the ``multipart-manifest=delete`` query parameter and the object is a static large object, the segment objects and manifest object are deleted. If you omit the - ``multipart- manifest=delete`` query parameter and the object is a + ``multipart-manifest=delete`` query parameter and the object is a static large object, the manifest object is deleted but the - segment objects are not deleted. For a bulk delete, the response - body looks the same as it does for a normal bulk delete. In - contrast, a plain object DELETE response has an empty body. + segment objects are not deleted. The response body will contain + the status of the deletion of every processed segment object. in: query required: false type: string @@ -862,6 +938,13 @@ multipart-manifest_head: in: query required: false type: string +multipart-manifest_put: + description: | + If you include the ``multipart-manifest=put`` query parameter, the object + is a static large object manifest and the body contains the manifest. + in: query + required: false + type: string path: description: | For a string value, returns the object names that @@ -878,11 +961,9 @@ prefix: type: string swiftinfo_expires: description: | - Filters the response by the expiration date and - time in `UNIX Epoch time stamp format - `_. For example, - ``1440619048`` is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 - GMT``. + The time at which ``swiftinfo_sig`` expires. The time is in + `UNIX Epoch time stamp format + `_. in: query required: false type: integer diff --git a/api-ref/source/samples/capabilities-list-response.json b/api-ref/source/samples/capabilities-list-response.json index bcc91f7d53..f082dc7b9e 100644 --- a/api-ref/source/samples/capabilities-list-response.json +++ b/api-ref/source/samples/capabilities-list-response.json @@ -2,6 +2,11 @@ "swift": { "version": "1.11.0" }, + "slo": { + "max_manifest_segments": 1000, + "max_manifest_size": 2097152, + "min_segment_size": 1 + }, "staticweb": {}, "tempurl": {} } diff --git a/api-ref/source/storage-account-services.inc b/api-ref/source/storage-account-services.inc index 17f228c543..4a543787cb 100644 --- a/api-ref/source/storage-account-services.inc +++ b/api-ref/source/storage-account-services.inc @@ -5,60 +5,10 @@ Accounts ======== Lists containers for an account. Creates, updates, shows, and -deletes account metadata. +deletes account metadata. For more information and concepts about +accounts see `Object Storage API overview +`_. -Account metadata operations work differently than container and -object metadata operations work. Depending on the contents of your -POST account metadata request, the Object Storage API updates the -metadata in one of these ways: - -**Account metadata operations** - -+----------------------------------------------------------+---------------------------------------------------------------+ -| POST request body contains | Description | -+----------------------------------------------------------+---------------------------------------------------------------+ -| A metadata key without a value. | The API removes the metadata item from the account. | -| | | -| The metadata key already exists for the account. | | -+----------------------------------------------------------+---------------------------------------------------------------+ -| A metadata key without a value. | The API ignores the metadata key. | -| | | -| The metadata key does not already exist for the account. | | -+----------------------------------------------------------+---------------------------------------------------------------+ -| A metadata key value. | The API updates the metadata key value for the account. | -| | | -| The metadata key already exists for the account. | | -+----------------------------------------------------------+---------------------------------------------------------------+ -| A metadata key value. | The API adds the metadata key and value pair, or item, to the | -| | account. | -| The metadata key does not already exist for the account. | | -+----------------------------------------------------------+---------------------------------------------------------------+ -| One or more account metadata items are omitted. | The API does not change the existing metadata items. | -| | | -| The metadata items already exist for the account. | | -+----------------------------------------------------------+---------------------------------------------------------------+ - - - -For these requests, specifying the ``X-Remove-Account-Meta-*`` -request header for the key with any value is equivalent to -specifying the ``X-Account-Meta-*`` request header with an empty -value. - -Metadata keys must be treated as case-insensitive at all times. -These keys can contain ASCII 7-bit characters that are not control -(0-31) characters, DEL, or a separator character, according to -`HTTP/1.1 `_ . -Also, Object Storage does not support the underscore character, -which it silently converts to a hyphen. - -The metadata values in Object Storage do not follow HTTP/1.1 rules -for character encodings. You must use a UTF-8 encoding to get a -byte array for any string that contains characters that are not in -the 7-bit ASCII 0-127 range. Otherwise, Object Storage returns the -404 response code for ISO-8859-1 characters in the 128-255 range, -which is a direct violation of the HTTP/1.1 `basic rules -`_. Show account details and list containers @@ -135,6 +85,7 @@ Request - prefix: prefix - delimiter: delimiter - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Newest: X-Newest - Accept: Accept - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -145,30 +96,39 @@ Response Parameters .. rest_parameters:: parameters.yaml - - Content-Length: Content-Length + - Content-Length: Content-Length_listing_resp - X-Account-Meta-name: X-Account-Meta-name - - X-Account-Object-Count: X-Account-Object-Count + - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2 - X-Timestamp: X-Timestamp - - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key - X-Trans-Id: X-Trans-Id - Date: Date - X-Account-Bytes-Used: X-Account-Bytes-Used - X-Account-Container-Count: X-Account-Container-Count - - Content-Type: Content-Type + - X-Account-Object-Count: X-Account-Object-Count + - X-Account-Storage-Policy-name-Bytes-Used: X-Account-Storage-Policy-name-Bytes-Used + - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count + - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count + - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp + - Content-Type: Content-Type_listing_resp - count: count - bytes: bytes - name: name -Response Example ----------------- +Response Example format=json +---------------------------- + +.. literalinclude:: samples/account-containers-list-http-response-json.txt +.. literalinclude:: samples/account-containers-list-response.json + + +Response Example format=xml +--------------------------- .. literalinclude:: samples/account-containers-list-http-response-xml.txt - :language: javascript - - +.. literalinclude:: samples/account-containers-list-response.xml @@ -179,21 +139,62 @@ Create, update, or delete account metadata Creates, updates, or deletes account metadata. -To create, update, or delete metadata, use the ``X-Account- -Meta-{name}`` request header, where ``{name}`` is the name of the +To create, update, or delete custom metadata, use the +``X-Account-Meta-{name}`` request header, where ``{name}`` is the name of the metadata item. -Subsequent requests for the same key and value pair overwrite the -existing value. +Account metadata operations work differently than how +object metadata operations work. Depending on the contents of your +POST account metadata request, the Object Storage API updates the +metadata as shown in the following table: + +**Account metadata operations** + ++----------------------------------------------------------+---------------------------------------------------------------+ +| POST request header contains | Result | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key without a value. | The API removes the metadata item from the account. | +| | | +| The metadata key already exists for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key without a value. | The API ignores the metadata key. | +| | | +| The metadata key does not already exist for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key value. | The API updates the metadata key value for the account. | +| | | +| The metadata key already exists for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key value. | The API adds the metadata key and value pair, or item, to the | +| | account. | +| The metadata key does not already exist for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| One or more account metadata items are omitted. | The API does not change the existing metadata items. | +| | | +| The metadata items already exist for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ + + To delete a metadata header, send an empty value for that header, such as for the ``X-Account-Meta-Book`` header. If the tool you use to communicate with Object Storage, such as an older version of cURL, does not support empty headers, send the ``X-Remove-Account- -Meta-{name}`` header with an arbitrary value. For example, ``X --Remove-Account-Meta-Book: x``. The operation ignores the arbitrary +Meta-{name}`` header with an arbitrary value. For example, +``X-Remove-Account-Meta-Book: x``. The operation ignores the arbitrary value. +Metadata keys (the name of the metadata) must be treated as case-insensitive +at all times. These keys can contain ASCII 7-bit characters that are not +control (0-31) characters, DEL, or a separator character, according to +`HTTP/1.1 `_ . +The underscore character is silently converted to a hyphen. + +.. include:: metadata_header_encoding.inc + +Subsequent requests for the same key and value pair overwrite the +existing value. + If the container already has other custom metadata items, a request to create, update, or delete metadata does not affect those items. @@ -270,11 +271,11 @@ Request - account: account - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2 - - X-Account-Meta-name: X-Account-Meta-name - - Content-Type: Content-Type - - X-Detect-Content-Type: X-Detect-Content-Type + - X-Account-Meta-name: X-Account-Meta-name_req + - X-Remove-Account-name: X-Remove-Account-name - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -285,8 +286,8 @@ Response Parameters - Date: Date - X-Timestamp: X-Timestamp - - Content-Length: Content-Length - - Content-Type: Content-Type + - Content-Length: Content-Length_cud_resp + - Content-Type: Content-Type_cud_resp - X-Trans-Id: X-Trans-Id @@ -353,6 +354,7 @@ Request - account: account - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Newest: X-Newest - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -362,17 +364,21 @@ Response Parameters .. rest_parameters:: parameters.yaml - - Content-Length: Content-Length + - Content-Length: Content-Length_cud_resp - X-Account-Meta-name: X-Account-Meta-name - - X-Account-Object-Count: X-Account-Object-Count + - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2 - X-Timestamp: X-Timestamp - - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key - X-Trans-Id: X-Trans-Id - Date: Date - X-Account-Bytes-Used: X-Account-Bytes-Used + - X-Account-Object-Count: X-Account-Object-Count - X-Account-Container-Count: X-Account-Container-Count - - Content-Type: Content-Type + - X-Account-Storage-Policy-name-Bytes-Used: X-Account-Storage-Policy-name-Bytes-Used + - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count + - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count + - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp + - Content-Type: Content-Type_cud_resp diff --git a/api-ref/source/storage-container-services.inc b/api-ref/source/storage-container-services.inc index 2213a78840..a979675328 100644 --- a/api-ref/source/storage-container-services.inc +++ b/api-ref/source/storage-container-services.inc @@ -6,7 +6,9 @@ Containers Lists objects in a container. Creates, shows details for, and deletes containers. Creates, updates, shows, and deletes container -metadata. +metadata. For more information and concepts about +containers see `Object Storage API overview +`_. Show container details and list objects @@ -17,8 +19,8 @@ Show container details and list objects Shows details for a container and lists objects, sorted by name, in the container. Specify query parameters in the request to filter the list and -return a subset of object names. Omit query parameters to return -the complete list of object names that are stored in the container, +return a subset of objects. Omit query parameters to return +a list of objects that are stored in the container, up to 10,000 names. The 10,000 maximum value is configurable. To view the value for the cluster, issue a GET ``/info`` request. @@ -28,23 +30,13 @@ Example requests and responses: - ``No Content (204)``. Success. The response body shows no objects. Either the container has no objects or you are paging through a - long list of names by using the ``marker``, ``limit``, or + long list of objects by using the ``marker``, ``limit``, or ``end_marker`` query parameter and you have reached the end of the list. If the container does not exist, the call returns the ``Not Found (404)`` response code. -The operation returns the ``Range Not Satisfiable (416)`` response -code for any ranged GET requests that specify more than: - -- Fifty ranges. - -- Three overlapping ranges. - -- Eight non-increasing ranges. - - Normal response codes: 200 Error response codes:416,404,204, @@ -64,11 +56,13 @@ Request - delimiter: delimiter - path: path - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Newest: X-Newest - Accept: Accept - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 - X-Trans-Id-Extra: X-Trans-Id-Extra + - X-Storage-Policy: X-Storage-Policy Response Parameters @@ -77,35 +71,42 @@ Response Parameters .. rest_parameters:: parameters.yaml - X-Container-Meta-name: X-Container-Meta-name - - Content-Length: Content-Length + - Content-Length: Content-Length_listing_resp - X-Container-Object-Count: X-Container-Object-Count + - X-Container-Bytes-Used: X-Container-Bytes-Used - Accept-Ranges: Accept-Ranges - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - - X-Container-Bytes-Used: X-Container-Bytes-Used - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Storage-Policy: X-Storage-Policy + - X-Container-Read: X-Container-Read_resp + - X-Container-Write: X-Container-Write_resp + - X-Container-Sync-Key: X-Container-Sync-Key_resp + - X-Container-Sync-To: X-Container-Sync-To_resp + - X-Versions-Location: X-Versions-Location_resp + - X-Versions-Mode: X-Versions-Mode_resp - X-Timestamp: X-Timestamp - X-Trans-Id: X-Trans-Id + - Content_Type: Content-Type_listing_resp - Date: Date - - Content-Type: Content-Type - hash: hash - last_modified: last_modified + - content_type: content_type - bytes: bytes - name: name - - content_type: content_type +Response Example format=json +---------------------------- -Response Example ----------------- +.. literalinclude:: samples/objects-list-http-response-json.txt +.. literalinclude:: samples/objects-list-response.json + + +Response Example format=xml +--------------------------- .. literalinclude:: samples/objects-list-http-response-xml.txt - :language: javascript - - - - - - +.. literalinclude:: samples/objects-list-response.xml Create container ================ @@ -119,6 +120,18 @@ issuing a PUT operation because the operation is idempotent: It creates a container or updates an existing container, as appropriate. +To create, update, or delete a custom metadata item, use the ``X +-Container-Meta-{name}`` header, where ``{name}`` is the name of +the metadata item. + +Metadata keys (the name of the metadata) must be treated as case-insensitive +at all times. These keys can contain ASCII 7-bit characters that are not +control (0-31) characters, DEL, or a separator character, according to +`HTTP/1.1 `_ . +The underscore character is silently converted to a hyphen. + +.. include:: metadata_header_encoding.inc + Example requests and responses: - Create a container with no metadata: @@ -148,6 +161,22 @@ Example requests and responses: + :: + + HTTP/1.1 201 Created + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37 + Date: Tue, 14 Jan 2014 19:25:43 GMT + +- Create a container with an ACL to allow anybody to get an object in the + marktwain container: + :: + + curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Read: .r:*" + + + :: HTTP/1.1 201 Created @@ -167,21 +196,21 @@ Request - account: account - container: container - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Container-Read: X-Container-Read - X-Container-Write: X-Container-Write - X-Container-Sync-To: X-Container-Sync-To - X-Container-Sync-Key: X-Container-Sync-Key - X-Versions-Location: X-Versions-Location - X-Versions-Mode: X-Versions-Mode - - X-Container-Meta-name: X-Container-Meta-name + - X-Container-Meta-name: X-Container-Meta-name_req - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers - - Content-Type: Content-Type - - X-Detect-Content-Type: X-Detect-Content-Type - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 - X-Trans-Id-Extra: X-Trans-Id-Extra + - X-Storage-Policy: X-Storage-Policy Response Parameters @@ -191,8 +220,8 @@ Response Parameters - Date: Date - X-Timestamp: X-Timestamp - - Content-Length: Content-Length - - Content-Type: Content-Type + - Content-Length: Content-Length_cud_resp + - Content-Type: Content-Type_cud_resp - X-Trans-Id: X-Trans-Id @@ -211,6 +240,14 @@ To create, update, or delete a custom metadata item, use the ``X -Container-Meta-{name}`` header, where ``{name}`` is the name of the metadata item. +Metadata keys (the name of the metadata) must be treated as case-insensitive +at all times. These keys can contain ASCII 7-bit characters that are not +control (0-31) characters, DEL, or a separator character, according to +`HTTP/1.1 `_ . +The underscore character is silently converted to a hyphen. + +.. include:: metadata_header_encoding.inc + Subsequent requests for the same key and value pair overwrite the previous value. @@ -297,6 +334,7 @@ Request - account: account - container: container - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Container-Read: X-Container-Read - X-Remove-Container-name: X-Remove-Container-name - X-Container-Write: X-Container-Write @@ -305,15 +343,13 @@ Request - X-Versions-Location: X-Versions-Location - X-Versions-Mode: X-Versions-Mode - X-Remove-Versions-Location: X-Remove-Versions-Location - - X-Container-Meta-name: X-Container-Meta-name + - X-Container-Meta-name: X-Container-Meta-name_req - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count - X-Container-Meta-Web-Directory-Type: X-Container-Meta-Web-Directory-Type - - Content-Type: Content-Type - - X-Detect-Content-Type: X-Detect-Content-Type - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -326,8 +362,8 @@ Response Parameters - Date: Date - X-Timestamp: X-Timestamp - - Content-Length: Content-Length - - Content-Type: Content-Type + - Content-Length: Content-Length_cud_resp + - Content-Type: Content-Type_cud_resp - X-Trans-Id: X-Trans-Id @@ -379,9 +415,8 @@ Request - account: account - container: container - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Newest: X-Newest - - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -390,28 +425,29 @@ Response Parameters .. rest_parameters:: parameters.yaml - - X-Container-Sync-Key: X-Container-Sync-Key - X-Container-Meta-name: X-Container-Meta-name - - Content-Length: Content-Length + - Content-Length: Content-Length_cud_resp - X-Container-Object-Count: X-Container-Object-Count - - X-Container-Write: X-Container-Write + - X-Container-Bytes-Used: X-Container-Bytes-Used + - X-Container-Write: X-Container-Write_resp + - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count - Accept-Ranges: Accept-Ranges - - X-Container-Read: X-Container-Read + - X-Container-Read: X-Container-Read_resp - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - - X-Container-Bytes-Used: X-Container-Bytes-Used - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 - X-Timestamp: X-Timestamp - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age + - X-Container-Sync-Key: X-Container-Sync-Key_resp + - X-Container-Sync-To: X-Container-Sync-To_resp - Date: Date - X-Trans-Id: X-Trans-Id - - X-Container-Sync-To: X-Container-Sync-To - - Content-Type: Content-Type - - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes - - X-Versions-Location: X-Versions-Location - - X-Versions-Mode: X-Versions-Mode + - Content-Type: Content-Type_cud_resp + - X-Versions-Location: X-Versions-Location_resp + - X-Versions-Mode: X-Versions-Mode_resp + - X-Storage-Policy: X-Storage-Policy @@ -483,8 +519,7 @@ Request - account: account - container: container - X-Auth-Token: X-Auth-Token - - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key - - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Service-Token: X-Service-Token - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -495,8 +530,8 @@ Response Parameters - Date: Date - X-Timestamp: X-Timestamp - - Content-Length: Content-Length - - Content-Type: Content-Type + - Content-Length: Content-Length_cud_resp + - Content-Type: Content-Type_cud_resp - X-Trans-Id: X-Trans-Id diff --git a/api-ref/source/storage-object-services.inc b/api-ref/source/storage-object-services.inc index d9ce9b3b81..5db102016f 100644 --- a/api-ref/source/storage-object-services.inc +++ b/api-ref/source/storage-object-services.inc @@ -6,7 +6,11 @@ Objects Creates, replaces, shows details for, and deletes objects. Copies objects from another object with a new or different name. Updates -object metadata. +object metadata. For more information and concepts about +objects see `Object Storage API overview +`_ +and `Large Objects +`_. Get object content and metadata @@ -96,9 +100,10 @@ Request .. rest_parameters:: parameters.yaml - account: account - - object: object - container: container + - object: object - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Newest: X-Newest - temp_url_sig: temp_url_sig - temp_url_expires: temp_url_expires @@ -117,20 +122,20 @@ Response Parameters .. rest_parameters:: parameters.yaml - - Content-Length: Content-Length - - X-Object-Meta-name: X-Object-Meta-name - - Content-Disposition: Content-Disposition - - Content-Encoding: Content-Encoding + - Content-Length: Content-Length_get_resp + - Content-Type: Content-Type_obj_resp + - X-Object-Meta-name: X-Object-Meta-name_resp + - Content-Disposition: Content-Disposition_resp + - Content-Encoding: Content-Encoding_resp - X-Delete-At: X-Delete-At - Accept-Ranges: Accept-Ranges - - X-Object-Manifest: X-Object-Manifest + - X-Object-Manifest: X-Object-Manifest_resp - Last-Modified: Last-Modified - - ETag: ETag + - ETag: ETag_obj_resp - X-Timestamp: X-Timestamp - X-Trans-Id: X-Trans-Id - Date: Date - X-Static-Large-Object: X-Static-Large-Object - - Content-Type: Content-Type @@ -157,6 +162,16 @@ is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you cannot copy objects larger than 5 GB. +To create custom metadata, use the +``X-Object-Meta-name`` header, where ``name`` is the name of the metadata +item. + +Metadata keys (the name of the metadata) must be treated as case-insensitive +at all times. These keys can contain ASCII 7-bit characters that are not +control (0-31) characters, DEL, or a separator character, according to +`HTTP/1.1 `_ . +The underscore character is silently converted to a hyphen. + Example requests and responses: - Create object: @@ -220,20 +235,20 @@ Request .. rest_parameters:: parameters.yaml - account: account - - object: object - container: container - - multipart-manifest: multipart-manifest + - object: object + - multipart-manifest: multipart-manifest_put - temp_url_sig: temp_url_sig - temp_url_expires: temp_url_expires - - filename: filename - X-Object-Manifest: X-Object-Manifest - X-Auth-Token: X-Auth-Token - - Content-Length: Content-Length + - X-Service-Token: X-Service-Token + - Content-Length: Content-Length_put_req - Transfer-Encoding: Transfer-Encoding - - Content-Type: Content-Type + - Content-Type: Content-Type_obj_cu_req - X-Detect-Content-Type: X-Detect-Content-Type - X-Copy-From: X-Copy-From - - ETag: ETag + - ETag: ETag_obj_req - Content-Disposition: Content-Disposition - Content-Encoding: Content-Encoding - X-Delete-At: X-Delete-At @@ -248,12 +263,12 @@ Response Parameters .. rest_parameters:: parameters.yaml - - Content-Length: Content-Length - - ETag: ETag + - Content-Length: Content-Length_cud_resp + - ETag: ETag_obj_received - X-Timestamp: X-Timestamp - X-Trans-Id: X-Trans-Id - Date: Date - - Content-Type: Content-Type + - Content-Type: Content-Type_obj_resp - last_modified: last_modified @@ -272,25 +287,33 @@ Copies an object to another object in the object store. You can copy an object to a new object with the same name. Copying to the same name is an alternative to using POST to add metadata to -an object. With POST , you must specify all the metadata. With COPY -, you can add additional metadata to the object. +an object. With POST, you must specify all the metadata. With COPY, +you can add additional metadata to the object. -With COPY , you can set the ``X-Fresh-Metadata`` header to ``true`` +With COPY, you can set the ``X-Fresh-Metadata`` header to ``true`` to copy the object without any existing metadata. Alternatively, you can use PUT with the ``X-Copy-From`` request header to accomplish the same operation as the COPY object operation. -The PUT operation always creates an object. If you use this +The COPY operation always creates an object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object. Consequently, this operation returns the ``Created (201)`` response code. -If you use this operation to copy a manifest object, the new object +Normally, if you use this operation to copy a manifest object, the new object is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you -cannot copy objects larger than 5 GB in size. All metadata is +cannot copy objects larger than 5 GB in size. + +To copy the manifest object, you include the +``multipart-manifest=get`` query string in the COPY request. +The new object contains the same manifest as the original. +The segment objects are not copied. Instead, both the original +and new manifest objects share the same set of segment objects. + +All metadata is preserved during the object copy. If you specify metadata on the request to copy the object, either PUT or COPY , the metadata overwrites any conflicting keys on the target (new) object. @@ -360,11 +383,14 @@ Request .. rest_parameters:: parameters.yaml - account: account - - object: object - container: container + - object: object + - multipart-manifest: multipart-manifest_copy - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - Destination: Destination - - Content-Type: Content-Type + - Destination-Account: Destination-Account + - Content-Type: Content-Type_obj_cu_req - Content-Encoding: Content-Encoding - Content-Disposition: Content-Disposition - X-Object-Meta-name: X-Object-Meta-name @@ -377,16 +403,16 @@ Response Parameters .. rest_parameters:: parameters.yaml - - Content-Length: Content-Length - - X-Object-Meta-name: X-Object-Meta-name + - Content-Length: Content-Length_cud_resp - X-Copied-From-Last-Modified: X-Copied-From-Last-Modified - X-Copied-From: X-Copied-From + - X-Copied-From-Account: X-Copied-From-Account - Last-Modified: Last-Modified - - ETag: ETag + - ETag: ETag_obj_copied - X-Timestamp: X-Timestamp - X-Trans-Id: X-Trans-Id - Date: Date - - Content-Type: Content-Type + - Content-Type: Content-Type_obj_resp @@ -399,18 +425,18 @@ Delete object Permanently deletes an object from the object store. -You can use the COPY method to copy the object to a new location. -Then, use the DELETE method to delete the original object. - Object deletion occurs immediately at request time. Any subsequent -GET , HEAD , POST , or DELETE operations return a ``404 Not Found`` +GET, HEAD, POST, or DELETE operations will return a ``404 Not Found`` error code. For static large object manifests, you can add the ``?multipart- manifest=delete`` query parameter. This operation deletes the -segment objects and if all deletions succeed, this operation +segment objects and, if all deletions succeed, this operation deletes the manifest object. +An alternative to using the DELETE operation is to use +the POST operation with the ``bulk-delete`` query parameter. + Example request and response: - Delete the ``helloworld`` object from the ``marktwain`` container: @@ -445,10 +471,11 @@ Request .. rest_parameters:: parameters.yaml - account: account - - object: object - container: container - - multipart-manifest: multipart-manifest + - object: object + - multipart-manifest: multipart-manifest_delete - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -459,8 +486,8 @@ Response Parameters - Date: Date - X-Timestamp: X-Timestamp - - Content-Length: Content-Length - - Content-Type: Content-Type + - Content-Length: Content-Length_cud_resp + - Content-Type: Content-Type_cud_resp - X-Trans-Id: X-Trans-Id @@ -474,10 +501,7 @@ Show object metadata Shows object metadata. -If the ``Content-Length`` response header is non-zero, the example -cURL command stalls after it prints the response headers because it -is waiting for a response body. However, the Object Storage system -does not return a response body for the HEAD operation. + Example requests and responses: @@ -485,7 +509,7 @@ Example requests and responses: :: - curl -i $publicURL/marktwain/goodbye -X HEAD -H "X-Auth-Token: $token" + curl $publicURL/marktwain/goodbye --head -H "X-Auth-Token: $token" @@ -503,6 +527,12 @@ Example requests and responses: X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f Date: Thu, 16 Jan 2014 21:13:19 GMT + Note: The ``--head`` option was used in the above example. If we had + used ``-i -X HEAD`` and the ``Content-Length`` response header is non-zero, + the cURL command stalls after it prints the response headers because it + is waiting for a response body. However, the Object Storage system + does not return a response body for the HEAD operation. + If the request succeeds, the operation returns the ``200`` response code. @@ -518,9 +548,10 @@ Request .. rest_parameters:: parameters.yaml - account: account - - object: object - container: container + - object: object - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - temp_url_sig: temp_url_sig - temp_url_expires: temp_url_expires - filename: filename @@ -534,20 +565,19 @@ Response Parameters .. rest_parameters:: parameters.yaml - - Last-Modified: Last-Modified - - Content-Length: Content-Length + - Content-Length: Content-Length_obj_head_resp - X-Object-Meta-name: X-Object-Meta-name - - Content-Disposition: Content-Disposition - - Content-Encoding: Content-Encoding + - Content-Disposition: Content-Disposition_resp + - Content-Encoding: Content-Encoding_resp - X-Delete-At: X-Delete-At - - X-Object-Manifest: X-Object-Manifest + - X-Object-Manifest: X-Object-Manifest_resp - Last-Modified: Last-Modified - - ETag: ETag + - ETag: ETag_obj_resp - X-Timestamp: X-Timestamp - X-Trans-Id: X-Trans-Id - Date: Date - X-Static-Large-Object: X-Static-Large-Object - - Content-Type: Content-Type + - Content-Type: Content-Type_obj_resp @@ -565,20 +595,25 @@ Create or update object metadata Creates or updates object metadata. -To create or update custom metadata, use the ``X-Object- -Meta-{name}`` header, where ``{name}`` is the name of the metadata +To create or update custom metadata, use the +``X-Object-Meta-name`` header, where ``name`` is the name of the metadata item. -In addition to the custom metadata, you can update the ``Content- -Type``, ``Content-Encoding``, ``Content-Disposition``, and ``X --Delete-At`` system metadata items. However you cannot update other +Metadata keys (the name of the metadata) must be treated as case-insensitive +at all times. These keys can contain ASCII 7-bit characters that are not +control (0-31) characters, DEL, or a separator character, according to +`HTTP/1.1 `_ . +The underscore character is silently converted to a hyphen. + +In addition to the custom metadata, you can update the +``Content-Type``, ``Content-Encoding``, ``Content-Disposition``, and +``X-Delete-At`` system metadata items. However you cannot update other system metadata, such as ``Content-Length`` or ``Last-Modified``. You can use COPY as an alternate to the POST operation by copying to the same object. With the POST operation you must specify all metadata items, whereas with the COPY operation, you need to specify only changed or additional items. - All metadata is preserved during the object copy. If you specify metadata on the request to copy the object, either PUT or COPY , the metadata overwrites any conflicting keys on the target (new) @@ -595,11 +630,19 @@ to define when to expire the object. When used as described in this section, the POST operation creates or replaces metadata. This form of the operation has no request -body. +body. There are alternate uses of the POST operation as follows: -You can also use the `form POST feature -`_ to upload objects. +- You can also use the `form POST feature + `_ to upload objects. + +- The POST operation when used with the ``bulk-delete`` query parameter + can be used to delete multiple objects and containers in a single + operation. + +- The POST operation when used with the ``extract-archive`` query parameter + can be used to upload an archive (tar file). The archive is then extracted + to create objects. Example requests and responses: @@ -659,16 +702,18 @@ Request .. rest_parameters:: parameters.yaml - account: account - - object: object - container: container + - object: object + - bulk-delete: bulk-delete + - extract-archive: extract-archive - X-Auth-Token: X-Auth-Token + - X-Service-Token: X-Service-Token - X-Object-Meta-name: X-Object-Meta-name - X-Delete-At: X-Delete-At - Content-Disposition: Content-Disposition - Content-Encoding: Content-Encoding - X-Delete-After: X-Delete-After - - Content-Type: Content-Type - - X-Detect-Content-Type: X-Detect-Content-Type + - Content-Type: Content-Type_obj_cu_req - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -679,8 +724,8 @@ Response Parameters - Date: Date - X-Timestamp: X-Timestamp - - Content-Length: Content-Length - - Content-Type: Content-Type + - Content-Length: Content-Length_cud_resp + - Content-Type: Content-Type_cud_resp - X-Trans-Id: X-Trans-Id diff --git a/api-ref/source/storage_info.inc b/api-ref/source/storage_info.inc index 60b4082f7c..0487210b3d 100644 --- a/api-ref/source/storage_info.inc +++ b/api-ref/source/storage_info.inc @@ -15,6 +15,11 @@ List activated capabilities Lists the activated capabilities for this version of the OpenStack Object Storage API. +Most of the information is "public" i.e. visible to all callers. However, some +configuration and capability items are reserved for the administrators of the +system. To access this data, the ``swiftinfo_sig`` and ``swiftinfo_expires`` +query parameters must be added to the request. + Normal response codes: 200 Error response codes: