Adds migrated API reference files
This brings in RST plus YAML files, migrated from the source for [0]. The migration explanation is found on the openstack-dev mailing list [1]. Project instruction is in the OpenStack Documentation Contributor Guide [2]. A patch for publishing this source is in [3]. The conf.py and the tox environment are standard across other projects. [0]http://developer.openstack.org/api-ref-objectstorage-v1.html [1]http://lists.openstack.org/pipermail/openstack-dev/2016-May/093765.html [2]http://docs.openstack.org/contributor-guide/api-guides.html [3]https://review.openstack.org/#/c/313015/ Change-Id: Ifebc65b188c4f2ba35b61c0deae5ec24401df7f9
This commit is contained in:
Cloud User
Andreas Jaeger
parent
c0217a4845
commit
4b13879680
221
api-ref/source/conf.py
Normal file
221
api-ref/source/conf.py
Normal file
@ -0,0 +1,221 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
#
|
||||
# swift documentation build configuration file
|
||||
#
|
||||
# This file is execfile()d with the current directory set to
|
||||
# its containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
import os
|
||||
from swift import __version__
|
||||
import subprocess
|
||||
import sys
|
||||
import warnings
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
sys.path.insert(0, os.path.abspath('../../'))
|
||||
sys.path.insert(0, os.path.abspath('../'))
|
||||
sys.path.insert(0, os.path.abspath('./'))
|
||||
|
||||
# -- General configuration ----------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
|
||||
extensions = [
|
||||
'os_api_ref',
|
||||
'oslosphinx',
|
||||
]
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The encoding of source files.
|
||||
#
|
||||
# source_encoding = 'utf-8'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'Object Storage API Reference'
|
||||
copyright = u'2010-present, OpenStack Foundation'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = __version__.rsplit('.', 1)[0]
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = __version__
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# language = None
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
# today = ''
|
||||
# Else, today_fmt is used as the format for a strftime call.
|
||||
# today_fmt = '%B %d, %Y'
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use
|
||||
# for all documents.
|
||||
# default_role = None
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
# add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
add_module_names = False
|
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||
# output. They are ignored by default.
|
||||
show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# -- Options for man page output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree for man pages.
|
||||
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
|
||||
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
||||
# Sphinx are currently 'default' and 'sphinxdoc'.
|
||||
# html_theme_path = ["."]
|
||||
# html_theme = '_theme'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
# html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory.
|
||||
# html_theme_path = []
|
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to
|
||||
# "<project> v<release> documentation".
|
||||
# html_title = None
|
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||
# html_short_title = None
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top
|
||||
# of the sidebar.
|
||||
# html_logo = None
|
||||
|
||||
# The name of an image file (within the static path) to use as favicon of the
|
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||
# pixels large.
|
||||
# html_favicon = None
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
#html_static_path = ['_static']
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
# html_last_updated_fmt = '%b %d, %Y'
|
||||
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
|
||||
"-n1"]
|
||||
try:
|
||||
html_last_updated_fmt = subprocess.Popen(
|
||||
git_cmd, stdout=subprocess.PIPE).communicate()[0]
|
||||
except OSError:
|
||||
warnings.warn('Cannot get last updated time from git repository. '
|
||||
'Not setting "html_last_updated_fmt".')
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
# html_use_smartypants = True
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
# html_sidebars = {}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
# html_additional_pages = {}
|
||||
|
||||
# If false, no module index is generated.
|
||||
# html_use_modindex = True
|
||||
|
||||
# If false, no index is generated.
|
||||
# html_use_index = True
|
||||
|
||||
# If true, the index is split into individual pages for each letter.
|
||||
# html_split_index = False
|
||||
|
||||
# If true, links to the reST sources are added to the pages.
|
||||
# html_show_sourcelink = True
|
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
# html_use_opensearch = ''
|
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
# html_file_suffix = ''
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'swiftdoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output -------------------------------------------------
|
||||
|
||||
# The paper size ('letter' or 'a4').
|
||||
# latex_paper_size = 'letter'
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
# latex_font_size = '10pt'
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'swift.tex', u'OpenStack Object Storage API Documentation',
|
||||
u'OpenStack Foundation', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
# the title page.
|
||||
# latex_logo = None
|
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||
# not chapters.
|
||||
# latex_use_parts = False
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
# latex_preamble = ''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
# latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
# latex_use_modindex = True
|
||||
13
api-ref/source/index.rst
Normal file
13
api-ref/source/index.rst
Normal file
@ -0,0 +1,13 @@
|
||||
:tocdepth: 2
|
||||
|
||||
===================
|
||||
Object Storage API
|
||||
===================
|
||||
|
||||
.. 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
|
||||
961
api-ref/source/parameters.yaml
Normal file
961
api-ref/source/parameters.yaml
Normal file
@ -0,0 +1,961 @@
|
||||
# variables in header
|
||||
Accept:
|
||||
description: |
|
||||
Instead of using the ``format`` query parameter,
|
||||
set this header to ``application/json``, ``application/xml``, or
|
||||
``text/xml``.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
Accept-Ranges:
|
||||
description: |
|
||||
The type of ranges that the object accepts.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Content-Disposition:
|
||||
description: |
|
||||
If set, 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.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
Content-Disposition_1:
|
||||
description: |
|
||||
If set, 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
|
||||
returned by this operation.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
Content-Encoding:
|
||||
description: |
|
||||
If set, the value of the ``Content-Encoding``
|
||||
metadata.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
Content-Encoding_1:
|
||||
description: |
|
||||
If set, 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:
|
||||
description: |
|
||||
If the operation succeeds, this value is zero
|
||||
(0). If the operation fails, this value is the length of the error
|
||||
text in the response body.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Content-Length_1:
|
||||
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.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Content-Length_3:
|
||||
description: |
|
||||
HEAD operations do not return content. The
|
||||
``Content-Length`` header value is not the size of the response
|
||||
body but is the size of the object, in bytes.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Content-Length_4:
|
||||
description: |
|
||||
The length of the object content in the response
|
||||
body, in bytes.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Content-Type:
|
||||
description: |
|
||||
Changes the MIME type for the object.
|
||||
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:
|
||||
description: |
|
||||
The MIME type of the list of names. If the
|
||||
operation fails, this value is the MIME type of the error text in
|
||||
the response body.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Date:
|
||||
description: |
|
||||
The transaction date and time.
|
||||
|
||||
The date and time stamp format is `ISO 8601
|
||||
<https://en.wikipedia.org/wiki/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.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Destination:
|
||||
description: |
|
||||
The container and object name of the destination
|
||||
object in the form of ``/container/object``. You must UTF-8-encode
|
||||
and then URL-encode the names of the destination container and
|
||||
object before you include them in this header.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
ETag:
|
||||
description: |
|
||||
The MD5 checksum of the copied object content.
|
||||
The value is not quoted.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
ETag_1:
|
||||
description: |
|
||||
The MD5 checksum value of the request body. For
|
||||
example, the MD5 checksum value of the object content. You are
|
||||
strongly recommended to compute the MD5 checksum value of object
|
||||
content and include it in the request. This enables the Object
|
||||
Storage API to check the integrity of the upload. The value is not
|
||||
quoted.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
ETag_2:
|
||||
description: |
|
||||
For objects smaller than 5 GB, this value is the
|
||||
MD5 checksum of the object content. The value is not quoted. For
|
||||
manifest objects, this value is the MD5 checksum of the
|
||||
concatenated string of MD5 checksums and ETags for each of the
|
||||
segments in the manifest, and not the MD5 checksum of the content
|
||||
that was downloaded. Also the value is enclosed in double-quote
|
||||
characters. You are strongly recommended to compute the MD5
|
||||
checksum of the response body as it is received and compare this
|
||||
value with the one in the ETag header. If they differ, the content
|
||||
was corrupted, so retry the operation.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
If-Match:
|
||||
description: |
|
||||
See `Request for Comments: 2616
|
||||
<http://www.ietf.org/rfc/rfc2616.txt>`_.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
If-Modified-Since:
|
||||
description: |
|
||||
See `Request for Comments: 2616
|
||||
<http://www.ietf.org/rfc/rfc2616.txt>`_.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
If-None-Match:
|
||||
description: |
|
||||
In combination with ``Expect: 100-Continue``,
|
||||
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
|
||||
type: string
|
||||
If-Unmodified-Since:
|
||||
description: |
|
||||
See `Request for Comments: 2616
|
||||
<http://www.ietf.org/rfc/rfc2616.txt>`_.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
Last-Modified:
|
||||
description: |
|
||||
The date and time when the object was created or its metadata was
|
||||
changed.
|
||||
|
||||
The date and time stamp format is `ISO 8601
|
||||
<https://en.wikipedia.org/wiki/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``.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
Range:
|
||||
description: |
|
||||
The ranges of content to get. You can use the
|
||||
``Range`` header to get portions of data by using one or more
|
||||
range specifications. To specify many ranges, separate the range
|
||||
specifications with a comma. The types of range specifications
|
||||
are: - **Byte range specification**. Use FIRST_BYTE_OFFSET to
|
||||
specify the start of the data range, and LAST_BYTE_OFFSET to
|
||||
specify the end. You can omit the LAST_BYTE_OFFSET and if you
|
||||
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 five 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 five
|
||||
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
|
||||
Transfer-Encoding:
|
||||
description: |
|
||||
Set to ``chunked`` to enable chunked transfer
|
||||
encoding. If used, do not set the ``Content-Length`` header to a
|
||||
non-zero value.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Account-Bytes-Used:
|
||||
description: |
|
||||
The total number of bytes that are stored in
|
||||
Object Storage for the account.
|
||||
in: header
|
||||
required: true
|
||||
type: integer
|
||||
X-Account-Container-Count:
|
||||
description: |
|
||||
The number of containers.
|
||||
in: header
|
||||
required: true
|
||||
type: integer
|
||||
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}``).
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Account-Meta-name_1:
|
||||
description: |
|
||||
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
|
||||
delete.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Account-Meta-Temp-URL-Key:
|
||||
description: |
|
||||
The secret key value for temporary URLs. If not
|
||||
set, this header is not returned in the response.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Account-Meta-Temp-URL-Key-2:
|
||||
description: |
|
||||
A second secret key value for temporary URLs. If
|
||||
not set, this header is not returned in the response.
|
||||
The second key enables you to rotate keys by having
|
||||
two active keys at the same time.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Account-Object-Count:
|
||||
description: |
|
||||
The number of objects in the account.
|
||||
in: header
|
||||
required: true
|
||||
type: integer
|
||||
X-Auth-Token:
|
||||
description: |
|
||||
Authentication token. If you omit this header,
|
||||
your request fails unless the account owner has granted you access
|
||||
through an access control list (ACL).
|
||||
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.
|
||||
in: header
|
||||
required: true
|
||||
type: integer
|
||||
X-Container-Meta-Access-Control-Allow-Origin:
|
||||
description: |
|
||||
Originating URLs allowed to make cross-origin
|
||||
requests (CORS), separated by spaces. This heading applies to the
|
||||
container only, and all objects within the container with this
|
||||
header applied are CORS-enabled for the allowed origin URLs. A
|
||||
browser (user-agent) typically issues a `preflighted request
|
||||
<https://developer.mozilla.org/en-
|
||||
US/docs/HTTP/Access_control_CORS>`_ , which is an OPTIONS call
|
||||
that verifies the origin is allowed to make the request. The
|
||||
Object Storage service returns 200 if the originating URL is
|
||||
listed in this header parameter, and issues a 401 if the
|
||||
originating URL is not allowed to make a cross-origin request.
|
||||
Once a 200 is returned, the browser makes a second request to the
|
||||
Object Storage service to retrieve the CORS-enabled object.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Meta-Access-Control-Expose-Headers:
|
||||
description: |
|
||||
Headers the Object Storage service exposes to the
|
||||
browser (technically, through the ``user-agent`` setting), in the
|
||||
request response, separated by spaces. By default the Object
|
||||
Storage service returns the following values for this header: -
|
||||
All “simple response headers” as listed on
|
||||
`http://www.w3.org/TR/cors/#simple-response-header
|
||||
<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``.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Meta-Access-Control-Max-Age:
|
||||
description: |
|
||||
Maximum time for the origin to hold the preflight
|
||||
results. A browser may make an OPTIONS call to verify the origin
|
||||
is allowed to make the request. Set the value to an integer number
|
||||
of seconds after the time that the request was received.
|
||||
in: header
|
||||
required: false
|
||||
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
|
||||
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.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Meta-Quota-Count:
|
||||
description: |
|
||||
Sets maximum object count of the container.
|
||||
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.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Meta-Temp-URL-Key:
|
||||
description: |
|
||||
The secret key value for temporary URLs.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Meta-Temp-URL-Key-2:
|
||||
description: |
|
||||
A second secret key value for temporary URLs. The
|
||||
second key enables you to rotate keys by having two active keys at
|
||||
the same time.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Meta-Web-Directory-Type:
|
||||
description: |
|
||||
Sets the content-type of directory marker
|
||||
objects. If the header is not set, default is
|
||||
``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
|
||||
0-byte objects with a content-type of ``text/directory`` as
|
||||
directories rather than objects.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Object-Count:
|
||||
description: |
|
||||
The number of objects.
|
||||
in: header
|
||||
required: true
|
||||
type: integer
|
||||
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.
|
||||
|
||||
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.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Read_1:
|
||||
description: |
|
||||
The ACL that grants read access. If not set, this
|
||||
header is not returned by this operation.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Sync-Key:
|
||||
description: |
|
||||
Sets the secret key for container
|
||||
synchronization. If you remove the secret key, synchronization is
|
||||
halted.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Sync-Key_1:
|
||||
description: |
|
||||
The secret key for container synchronization. If
|
||||
not set, this header is not returned by this operation.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Sync-To:
|
||||
description: |
|
||||
Sets the destination for container
|
||||
synchronization. Used with the secret key indicated in the ``X
|
||||
-Container-Sync-Key`` header. If you want to stop a container from
|
||||
synchronizing, send a blank value for the ``X-Container-Sync-Key``
|
||||
header.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Sync-To_1:
|
||||
description: |
|
||||
The destination for container synchronization. If
|
||||
not set, this header is not returned by this operation.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Write:
|
||||
description: |
|
||||
Sets an ACL that grants write access.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Container-Write_1:
|
||||
description: |
|
||||
The ACL that grants write access. If not set,
|
||||
this header is not returned by this operation.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Copied-From:
|
||||
description: |
|
||||
For a copied object, shows the container and
|
||||
object name from which the new object was copied. The value is in
|
||||
the ``{container}/{object}`` format.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Copied-From-Last-Modified:
|
||||
description: |
|
||||
For a copied object, the date and time in `UNIX
|
||||
Epoch time stamp format
|
||||
<https://en.wikipedia.org/wiki/Unix_time>`_ when the container and
|
||||
object name from which the new object was copied was last
|
||||
modified. For example, ``1440619048`` is equivalent to ``Mon,
|
||||
Wed, 26 Aug 2015 19:57:28 GMT``.
|
||||
in: header
|
||||
required: false
|
||||
type: integer
|
||||
X-Copy-From:
|
||||
description: |
|
||||
If set, this is the name of an object used to
|
||||
create the new object by copying the ``X-Copy-From`` object. The
|
||||
value is in form ``{container}/{object}``. You must UTF-8-encode
|
||||
and then URL-encode the names of the container and object before
|
||||
you include them in the header. Using PUT with ``X-Copy-From``
|
||||
has the same effect as using the COPY operation to copy an object.
|
||||
Using ``Range`` header with ``X-Copy-From`` will create a new
|
||||
partial copied object with bytes set by ``Range``.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
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.
|
||||
in: header
|
||||
required: false
|
||||
type: integer
|
||||
X-Delete-At:
|
||||
description: |
|
||||
The date and time in `UNIX Epoch time stamp
|
||||
format <https://en.wikipedia.org/wiki/Unix_time>`_ when the system
|
||||
removes the object. For example, ``1440619048`` is equivalent to
|
||||
``Mon, Wed, 26 Aug 2015 19:57:28 GMT``.
|
||||
in: header
|
||||
required: false
|
||||
type: integer
|
||||
X-Delete-At_1:
|
||||
description: |
|
||||
If set, the date and time in `UNIX Epoch time
|
||||
stamp format <https://en.wikipedia.org/wiki/Unix_time>`_ 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.
|
||||
in: header
|
||||
required: false
|
||||
type: boolean
|
||||
X-Fresh-Metadata:
|
||||
description: |
|
||||
Enables object creation that omits existing user
|
||||
metadata. If set to ``true``, the COPY request creates an object
|
||||
without existing user metadata. Default value is ``false``.
|
||||
in: header
|
||||
required: false
|
||||
type: boolean
|
||||
X-Newest:
|
||||
description: |
|
||||
If set to true , Object Storage queries all
|
||||
replicas to return the most recent one. If you omit this header,
|
||||
Object Storage responds faster after it finds one valid replica.
|
||||
Because setting this header to true is more expensive for the back
|
||||
end, use it only when it is absolutely needed.
|
||||
in: header
|
||||
required: false
|
||||
type: boolean
|
||||
X-Object-Manifest:
|
||||
description: |
|
||||
Set to specify that 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``.
|
||||
You must UTF-8-encode and then URL-encode the names of the
|
||||
container and prefix before you include them in this header.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Object-Manifest_1:
|
||||
description: |
|
||||
If set, to 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
|
||||
required: false
|
||||
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.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Object-Meta-name_1:
|
||||
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.
|
||||
in: header
|
||||
required: true
|
||||
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.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Remove-Versions-Location:
|
||||
description: |
|
||||
Set to any value to disable versioning.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Static-Large-Object:
|
||||
description: |
|
||||
Set to ``true`` if this object is a static large
|
||||
object manifest object.
|
||||
in: header
|
||||
required: true
|
||||
type: boolean
|
||||
X-Timestamp:
|
||||
description: |
|
||||
The date and time in `UNIX Epoch time stamp
|
||||
format <https://en.wikipedia.org/wiki/Unix_time>`_ when the
|
||||
account, container, or object was initially created as a current
|
||||
version. For example, ``1440619048`` is equivalent to ``Mon, Wed,
|
||||
26 Aug 2015 19:57:28 GMT``.
|
||||
in: header
|
||||
required: true
|
||||
type: integer
|
||||
X-Trans-Id:
|
||||
description: |
|
||||
A unique transaction ID for this request. Your
|
||||
service provider might need this value if you report a problem.
|
||||
in: header
|
||||
required: true
|
||||
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
|
||||
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
|
||||
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
|
||||
<http://docs.openstack.org/user-
|
||||
guide/cli_swift_large_object_creation.html>`_ 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
|
||||
receive responses. The operator can search for the extra
|
||||
information in the logs.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Versions-Location:
|
||||
description: |
|
||||
Enables versioning on this container. The value
|
||||
is the name of another container. You must UTF-8-encode and then
|
||||
URL-encode the name before you include it in the header. To
|
||||
disable versioning, set the header to an empty string.
|
||||
in: header
|
||||
required: false
|
||||
type: string
|
||||
X-Versions-Location_1:
|
||||
description: |
|
||||
Enables versioning on this container. The value
|
||||
is the name of another container. You must UTF-8-encode and then
|
||||
URL-encode the name before you include it in the header. To
|
||||
disable versioning, set the header to an empty string.
|
||||
in: header
|
||||
required: true
|
||||
type: string
|
||||
|
||||
# variables in path
|
||||
account:
|
||||
description: |
|
||||
The unique name for the account. An account is
|
||||
also known as the project or tenant.
|
||||
in: path
|
||||
required: false
|
||||
type: string
|
||||
container:
|
||||
description: |
|
||||
The unique 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``.
|
||||
in: path
|
||||
required: false
|
||||
type: string
|
||||
object:
|
||||
description: |
|
||||
The unique name for the object.
|
||||
in: path
|
||||
required: false
|
||||
type: string
|
||||
|
||||
# variables in query
|
||||
delimiter:
|
||||
description: |
|
||||
Delimiter value, which returns the object names
|
||||
that are nested in the container. If you do not set a prefix and
|
||||
set the delimiter to "/" you may get unexpected results where all
|
||||
the objects are returned instead of only those with the delimiter
|
||||
set.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
end_marker:
|
||||
description: |
|
||||
For a string value, x , returns container names
|
||||
that are less than the marker value.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
filename:
|
||||
description: |
|
||||
Overrides the default file name. Object Storage
|
||||
generates a default file name for GET temporary URLs that is based
|
||||
on the object name. Object Storage returns this value in the
|
||||
``Content-Disposition`` response header. Browsers can interpret
|
||||
this file name value as a file attachment to save. For more
|
||||
information about temporary URLs, see `Temporary URL middleware
|
||||
<http://docs.openstack.org/developer/
|
||||
swift/api/temporary_url_middleware.html>`_.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
format:
|
||||
description: |
|
||||
The response format. Valid values are ``json``,
|
||||
``xml``, or ``plain``. The default is ``plain``. If you append
|
||||
the ``format=xml`` or ``format=json`` query parameter to the
|
||||
storage account URL, the response shows extended container
|
||||
information serialized in that format. If you append the
|
||||
``format=plain`` query parameter, the response lists the container
|
||||
names separated by newlines.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
limit:
|
||||
description: |
|
||||
For an integer value n , limits the number of
|
||||
results to n .
|
||||
in: query
|
||||
required: false
|
||||
type: integer
|
||||
marker:
|
||||
description: |
|
||||
For a string value, x , returns container names
|
||||
that are greater than the marker value.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
multipart-manifest:
|
||||
description: |
|
||||
If ``?multipart-manifest=put``, the object is a
|
||||
static large object manifest and the body contains the manifest.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
multipart-manifest_1:
|
||||
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
|
||||
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.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
multipart-manifest_2:
|
||||
description: |
|
||||
If you include the ``multipart-manifest=get``
|
||||
query parameter and the object is a large object, the object
|
||||
contents are not returned. Instead, the manifest is returned in
|
||||
the ``X-Object-Manifest`` response header for dynamic large
|
||||
objects or in the response body for static large objects.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
path:
|
||||
description: |
|
||||
For a string value, returns the object names that
|
||||
are nested in the pseudo path.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
prefix:
|
||||
description: |
|
||||
Prefix value. Named items in the response begin
|
||||
with this value.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
swiftinfo_expires:
|
||||
description: |
|
||||
Filters the response by the expiration date and
|
||||
time in `UNIX Epoch time stamp format
|
||||
<https://en.wikipedia.org/wiki/Unix_time>`_. For example,
|
||||
``1440619048`` is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28
|
||||
GMT``.
|
||||
in: query
|
||||
required: false
|
||||
type: integer
|
||||
swiftinfo_sig:
|
||||
description: |
|
||||
A hash-based message authentication code (HMAC)
|
||||
that enables access to administrator-only information. To use this
|
||||
parameter, the ``swiftinfo_expires`` parameter is also required.
|
||||
in: query
|
||||
required: false
|
||||
type: string
|
||||
temp_url_expires:
|
||||
description: |
|
||||
The date and time in `UNIX Epoch time stamp
|
||||
format <https://en.wikipedia.org/wiki/Unix_time>`_ when the
|
||||
signature for temporary URLs expires. For example, ``1440619048``
|
||||
is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. For more
|
||||
information about temporary URLs, see `Temporary URL middleware
|
||||
<http://docs.openstack.org/developer/swift/api/temporary
|
||||
_url_middleware.html>`_.
|
||||
in: query
|
||||
required: true
|
||||
type: integer
|
||||
temp_url_sig:
|
||||
description: |
|
||||
Used with temporary URLs to sign the request with
|
||||
an HMAC-SHA1 cryptographic signature that defines the allowed HTTP
|
||||
method, expiration date, full path to the object, and the secret
|
||||
key for the temporary URL. For more information about temporary
|
||||
URLs, see `Temporary URL middleware
|
||||
<http://docs.openstack.org/developer/swif
|
||||
t/api/temporary_url_middleware.html>`_.
|
||||
in: query
|
||||
required: true
|
||||
type: string
|
||||
|
||||
# variables in body
|
||||
bytes:
|
||||
description: |
|
||||
The total number of bytes that are stored in
|
||||
Object Storage for the account.
|
||||
in: body
|
||||
required: true
|
||||
type: integer
|
||||
content_type:
|
||||
description: |
|
||||
The content type of the object.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
count:
|
||||
description: |
|
||||
The number of objects in the container.
|
||||
in: body
|
||||
required: true
|
||||
type: integer
|
||||
hash:
|
||||
description: |
|
||||
The MD5 checksum value of the object content.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
last_modified:
|
||||
description: |
|
||||
The date and time when the object was last modified.
|
||||
|
||||
The date and time stamp format is `ISO 8601
|
||||
<https://en.wikipedia.org/wiki/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``.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
name:
|
||||
description: |
|
||||
The name of the container.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
|
||||
|
||||
@ -0,0 +1 @@
|
||||
curl -i https://23.253.72.207/v1/$account?format=json -X GET -H "X-Auth-Token: $token"
|
||||
@ -0,0 +1,2 @@
|
||||
curl -i https://23.253.72.207/v1/$account?format=xml \
|
||||
-X GET -H "X-Auth-Token: $token"
|
||||
@ -0,0 +1,11 @@
|
||||
HTTP/1.1 200 OK
|
||||
Content-Length: 96
|
||||
X-Account-Object-Count: 1
|
||||
X-Timestamp: 1389453423.35964
|
||||
X-Account-Meta-Subject: Literature
|
||||
X-Account-Bytes-Used: 14
|
||||
X-Account-Container-Count: 2
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Accept-Ranges: bytes
|
||||
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
|
||||
Date: Fri, 17 Jan 2014 15:59:33 GMT
|
||||
@ -0,0 +1,11 @@
|
||||
HTTP/1.1 200 OK
|
||||
Content-Length: 262
|
||||
X-Account-Object-Count: 1
|
||||
X-Timestamp: 1389453423.35964
|
||||
X-Account-Meta-Subject: Literature
|
||||
X-Account-Bytes-Used: 14
|
||||
X-Account-Container-Count: 2
|
||||
Content-Type: application/xml; charset=utf-8
|
||||
Accept-Ranges: bytes
|
||||
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
|
||||
Date: Fri, 17 Jan 2014 16:03:23 GMT
|
||||
12
api-ref/source/samples/account-containers-list-response.json
Normal file
12
api-ref/source/samples/account-containers-list-response.json
Normal file
@ -0,0 +1,12 @@
|
||||
[
|
||||
{
|
||||
"count": 0,
|
||||
"bytes": 0,
|
||||
"name": "janeausten"
|
||||
},
|
||||
{
|
||||
"count": 1,
|
||||
"bytes": 14,
|
||||
"name": "marktwain"
|
||||
}
|
||||
]
|
||||
13
api-ref/source/samples/account-containers-list-response.xml
Normal file
13
api-ref/source/samples/account-containers-list-response.xml
Normal file
@ -0,0 +1,13 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<account name="my_account">
|
||||
<container>
|
||||
<name>janeausten</name>
|
||||
<count>0</count>
|
||||
<bytes>0</bytes>
|
||||
</container>
|
||||
<container>
|
||||
<name>marktwain</name>
|
||||
<count>1</count>
|
||||
<bytes>14</bytes>
|
||||
</container>
|
||||
</account>
|
||||
7
api-ref/source/samples/capabilities-list-response.json
Normal file
7
api-ref/source/samples/capabilities-list-response.json
Normal file
@ -0,0 +1,7 @@
|
||||
{
|
||||
"swift": {
|
||||
"version": "1.11.0"
|
||||
},
|
||||
"staticweb": {},
|
||||
"tempurl": {}
|
||||
}
|
||||
3
api-ref/source/samples/containers-list-http-request.txt
Normal file
3
api-ref/source/samples/containers-list-http-request.txt
Normal file
@ -0,0 +1,3 @@
|
||||
GET /{api_version}/{account} HTTP/1.1
|
||||
Host: storage.swiftdrive.com
|
||||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||||
9
api-ref/source/samples/containers-list-http-response.txt
Normal file
9
api-ref/source/samples/containers-list-http-response.txt
Normal file
@ -0,0 +1,9 @@
|
||||
HTTP/1.1 200 Ok
|
||||
Date: Thu, 07 Jun 2010 18:57:07 GMT
|
||||
Content-Type: text/plain; charset=UTF-8
|
||||
Content-Length: 32
|
||||
|
||||
images
|
||||
movies
|
||||
documents
|
||||
backups
|
||||
14
api-ref/source/samples/endpoints-list-response-headers.json
Normal file
14
api-ref/source/samples/endpoints-list-response-headers.json
Normal file
@ -0,0 +1,14 @@
|
||||
{
|
||||
"endpoints": [
|
||||
"http://storage01.swiftdrive.com:6008/d8/583/AUTH_dev/EC_cont1/obj",
|
||||
"http://storage02.swiftdrive.com:6008/d2/583/AUTH_dev/EC_cont1/obj",
|
||||
"http://storage02.swiftdrive.com:6006/d3/583/AUTH_dev/EC_cont1/obj",
|
||||
"http://storage02.swiftdrive.com:6008/d5/583/AUTH_dev/EC_cont1/obj",
|
||||
"http://storage01.swiftdrive.com:6007/d7/583/AUTH_dev/EC_cont1/obj",
|
||||
"http://storage02.swiftdrive.com:6007/d4/583/AUTH_dev/EC_cont1/obj",
|
||||
"http://storage01.swiftdrive.com:6006/d6/583/AUTH_dev/EC_cont1/obj"
|
||||
],
|
||||
"headers": {
|
||||
"X-Backend-Storage-Policy-Index": "2"
|
||||
}
|
||||
}
|
||||
8
api-ref/source/samples/endpoints-list-response.json
Normal file
8
api-ref/source/samples/endpoints-list-response.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"endpoints": [
|
||||
"http://storage02.swiftdrive:6002/d2/617/AUTH_dev",
|
||||
"http://storage01.swiftdrive:6002/d8/617/AUTH_dev",
|
||||
"http://storage01.swiftdrive:6002/d11/617/AUTH_dev"
|
||||
],
|
||||
"headers": {}
|
||||
}
|
||||
1
api-ref/source/samples/goodbyeworld.txt
Normal file
1
api-ref/source/samples/goodbyeworld.txt
Normal file
@ -0,0 +1 @@
|
||||
Goodbye World!
|
||||
1
api-ref/source/samples/helloworld.txt
Normal file
1
api-ref/source/samples/helloworld.txt
Normal file
@ -0,0 +1 @@
|
||||
Hello World Again!
|
||||
10
api-ref/source/samples/objects-list-http-response-json.txt
Normal file
10
api-ref/source/samples/objects-list-http-response-json.txt
Normal file
@ -0,0 +1,10 @@
|
||||
HTTP/1.1 200 OK
|
||||
Content-Length: 341
|
||||
X-Container-Object-Count: 2
|
||||
Accept-Ranges: bytes
|
||||
X-Container-Meta-Book: TomSawyer
|
||||
X-Timestamp: 1389727543.65372
|
||||
X-Container-Bytes-Used: 26
|
||||
Content-Type: application/json; charset=utf-8
|
||||
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
|
||||
Date: Wed, 15 Jan 2014 16:57:35 GMT
|
||||
10
api-ref/source/samples/objects-list-http-response-xml.txt
Normal file
10
api-ref/source/samples/objects-list-http-response-xml.txt
Normal file
@ -0,0 +1,10 @@
|
||||
HTTP/1.1 200 OK
|
||||
Content-Length: 500
|
||||
X-Container-Object-Count: 2
|
||||
Accept-Ranges: bytes
|
||||
X-Container-Meta-Book: TomSawyer
|
||||
X-Timestamp: 1389727543.65372
|
||||
X-Container-Bytes-Used: 26
|
||||
Content-Type: application/xml; charset=utf-8
|
||||
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
|
||||
Date: Wed, 15 Jan 2014 16:59:35 GMT
|
||||
16
api-ref/source/samples/objects-list-response.json
Normal file
16
api-ref/source/samples/objects-list-response.json
Normal file
@ -0,0 +1,16 @@
|
||||
[
|
||||
{
|
||||
"hash": "451e372e48e0f6b1114fa0724aa79fa1",
|
||||
"last_modified": "2014-01-15T16:41:49.390270",
|
||||
"bytes": 14,
|
||||
"name": "goodbye",
|
||||
"content_type": "application/octet-stream"
|
||||
},
|
||||
{
|
||||
"hash": "ed076287532e86365e841e92bfc50d8c",
|
||||
"last_modified": "2014-01-15T16:37:43.427570",
|
||||
"bytes": 12,
|
||||
"name": "helloworld",
|
||||
"content_type": "application/octet-stream"
|
||||
}
|
||||
]
|
||||
17
api-ref/source/samples/objects-list-response.xml
Normal file
17
api-ref/source/samples/objects-list-response.xml
Normal file
@ -0,0 +1,17 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<container name="marktwain">
|
||||
<object>
|
||||
<name>goodbye</name>
|
||||
<hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
|
||||
<bytes>14</bytes>
|
||||
<content_type>application/octet-stream</content_type>
|
||||
<last_modified>2014-01-15T16:41:49.390270</last_modified>
|
||||
</object>
|
||||
<object>
|
||||
<name>helloworld</name>
|
||||
<hash>ed076287532e86365e841e92bfc50d8c</hash>
|
||||
<bytes>12</bytes>
|
||||
<content_type>application/octet-stream</content_type>
|
||||
<last_modified>2014-01-15T16:37:43.427570</last_modified>
|
||||
</object>
|
||||
</container>
|
||||
380
api-ref/source/storage-account-services.inc
Normal file
380
api-ref/source/storage-account-services.inc
Normal file
@ -0,0 +1,380 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
========
|
||||
Accounts
|
||||
========
|
||||
|
||||
Lists containers for an account. Creates, updates, shows, and
|
||||
deletes account metadata.
|
||||
|
||||
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 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
|
||||
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
|
||||
<http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2>`_.
|
||||
|
||||
|
||||
Show account details and list containers
|
||||
========================================
|
||||
|
||||
.. rest_method:: GET /v1/{account}
|
||||
|
||||
Shows details for an account and lists containers, sorted by name, in the account.
|
||||
|
||||
The sort order for the name is based on a binary comparison, a
|
||||
single built-in collating sequence that compares string data by
|
||||
using the SQLite memcmp() function, regardless of text encoding.
|
||||
See `Collating Sequences
|
||||
<http://www.sqlite.org/datatype3.html#collation>`_.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Show account details and list containers and ask for a JSON
|
||||
response:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
- List containers and ask for an XML response:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
The response body returns a list of containers. The default
|
||||
response (``text/plain``) returns one container per line.
|
||||
|
||||
If you use query parameters to page through a long list of
|
||||
containers, you have reached the end of the list if the number of
|
||||
items in the returned list is less than the request ``limit``
|
||||
value. The list contains more items if the number of items in the
|
||||
returned list equals the ``limit`` value.
|
||||
|
||||
When asking for a list of containers and there are none, the
|
||||
response behavior changes depending on whether the request format
|
||||
is text, JSON, or XML. For a text response, you get a 204 , because
|
||||
there is no content. However, for a JSON or XML response, you get a
|
||||
200 with content indicating an empty array.
|
||||
|
||||
If the request succeeds, the operation returns one of these status
|
||||
codes:
|
||||
|
||||
- ``OK (200)``. Success. The response body lists the containers.
|
||||
|
||||
- ``No Content (204)``. Success. The response body shows no
|
||||
containers. Either the account has no containers or you are
|
||||
paging through a long list of names by using the ``marker``,
|
||||
``limit``, or ``end_marker`` query parameter and you have reached
|
||||
the end of the list.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- end_marker: end_marker
|
||||
- format: format
|
||||
- prefix: prefix
|
||||
- delimiter: delimiter
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- X-Newest: X-Newest
|
||||
- Accept: Accept
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Content-Length: Content-Length
|
||||
- X-Account-Meta-name: X-Account-Meta-name
|
||||
- X-Account-Object-Count: X-Account-Object-Count
|
||||
- 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
|
||||
- count: count
|
||||
- bytes: bytes
|
||||
- name: name
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/account-containers-list-http-response-xml.txt
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Create, update, or delete account metadata
|
||||
==========================================
|
||||
|
||||
.. rest_method:: POST /v1/{account}
|
||||
|
||||
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
|
||||
metadata item.
|
||||
|
||||
Subsequent requests for the same key and value pair overwrite the
|
||||
existing value.
|
||||
|
||||
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
|
||||
value.
|
||||
|
||||
If the container already has other custom metadata items, a request
|
||||
to create, update, or delete metadata does not affect those items.
|
||||
|
||||
This operation does not accept a request body.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Create account metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Book: MobyDick" -H "X-Account-Meta-Subject: Literature"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx8c2dd6aee35442a4a5646-0052d954fb
|
||||
Date: Fri, 17 Jan 2014 16:06:19 GMT
|
||||
|
||||
|
||||
- Update account metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Subject: AmericanLiterature"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx1439b96137364ab581156-0052d95532
|
||||
Date: Fri, 17 Jan 2014 16:07:14 GMT
|
||||
|
||||
|
||||
- Delete account metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Remove-Account-Meta-Subject: x"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx411cf57701424da99948a-0052d9556f
|
||||
Date: Fri, 17 Jan 2014 16:08:15 GMT
|
||||
|
||||
|
||||
If the request succeeds, the operation returns the ``No Content
|
||||
(204)`` response code.
|
||||
|
||||
To confirm your changes, issue a show account metadata request.
|
||||
|
||||
Error response codes:204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- X-Auth-Token: X-Auth-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-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Date: Date
|
||||
- X-Timestamp: X-Timestamp
|
||||
- Content-Length: Content-Length
|
||||
- Content-Type: Content-Type
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Show account metadata
|
||||
=====================
|
||||
|
||||
.. rest_method:: HEAD /v1/{account}
|
||||
|
||||
Shows metadata for an account.
|
||||
|
||||
Metadata for the account includes:
|
||||
|
||||
- Number of containers
|
||||
|
||||
- Number of objects
|
||||
|
||||
- Total number of bytes that are stored in Object Storage for the
|
||||
account
|
||||
|
||||
Because the storage system can store large amounts of data, take
|
||||
care when you represent the total bytes response as an integer;
|
||||
when possible, convert it to a 64-bit unsigned integer if your
|
||||
platform supports that primitive type.
|
||||
|
||||
Do not include metadata headers in this request.
|
||||
|
||||
Show account metadata request:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL -X HEAD -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
X-Account-Object-Count: 1
|
||||
X-Account-Meta-Book: MobyDick
|
||||
X-Timestamp: 1389453423.35964
|
||||
X-Account-Bytes-Used: 14
|
||||
X-Account-Container-Count: 2
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
Accept-Ranges: bytes
|
||||
X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4
|
||||
Date: Fri, 17 Jan 2014 16:09:56 GMT
|
||||
|
||||
|
||||
If the account or authentication token is not valid, the operation
|
||||
returns the ``Unauthorized (401)`` response code.
|
||||
|
||||
Error response codes:204,401,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- X-Newest: X-Newest
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Content-Length: Content-Length
|
||||
- X-Account-Meta-name: X-Account-Meta-name
|
||||
- X-Account-Object-Count: X-Account-Object-Count
|
||||
- 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
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
503
api-ref/source/storage-container-services.inc
Normal file
503
api-ref/source/storage-container-services.inc
Normal file
@ -0,0 +1,503 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
==========
|
||||
Containers
|
||||
==========
|
||||
|
||||
Lists objects in a container. Creates, shows details for, and
|
||||
deletes containers. Creates, updates, shows, and deletes container
|
||||
metadata.
|
||||
|
||||
|
||||
Show container details and list objects
|
||||
=======================================
|
||||
|
||||
.. rest_method:: GET /v1/{account}/{container}
|
||||
|
||||
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,
|
||||
up to 10,000 names. The 10,000 maximum value is configurable. To
|
||||
view the value for the cluster, issue a GET ``/info`` request.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- ``OK (200)``. Success. The response body lists the objects.
|
||||
|
||||
- ``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
|
||||
``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,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- container: container
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- end_marker: end_marker
|
||||
- prefix: prefix
|
||||
- format: format
|
||||
- delimiter: delimiter
|
||||
- path: path
|
||||
- X-Auth-Token: X-Auth-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
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- X-Container-Meta-name: X-Container-Meta-name
|
||||
- Content-Length: Content-Length
|
||||
- X-Container-Object-Count: X-Container-Object-Count
|
||||
- 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-Timestamp: X-Timestamp
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
- Date: Date
|
||||
- Content-Type: Content-Type
|
||||
- hash: hash
|
||||
- last_modified: last_modified
|
||||
- bytes: bytes
|
||||
- name: name
|
||||
- content_type: content_type
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/objects-list-http-response-xml.txt
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Create container
|
||||
================
|
||||
|
||||
.. rest_method:: PUT /v1/{account}/{container}
|
||||
|
||||
Creates a container.
|
||||
|
||||
You do not need to check whether a container already exists before
|
||||
issuing a PUT operation because the operation is idempotent: It
|
||||
creates a container or updates an existing container, as
|
||||
appropriate.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Create a container with no metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
|
||||
Date: Tue, 14 Jan 2014 19:09:10 GMT
|
||||
|
||||
|
||||
- Create a container with metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
Error response codes:201,204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-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-Container-Meta-name: X-Container-Meta-name
|
||||
- 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
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Date: Date
|
||||
- X-Timestamp: X-Timestamp
|
||||
- Content-Length: Content-Length
|
||||
- Content-Type: Content-Type
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Create, update, or delete container metadata
|
||||
============================================
|
||||
|
||||
.. rest_method:: POST /v1/{account}/{container}
|
||||
|
||||
Creates, updates, or deletes custom metadata for a container.
|
||||
|
||||
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.
|
||||
|
||||
Subsequent requests for the same key and value pair overwrite the
|
||||
previous value.
|
||||
|
||||
To delete container metadata, send an empty value for that header,
|
||||
such as for the ``X-Container-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-
|
||||
Container-Meta-{name}`` header with an arbitrary value. For
|
||||
example, ``X-Remove-Container-Meta-Book: x``. The operation ignores
|
||||
the arbitrary value.
|
||||
|
||||
If the container already has other custom metadata items, a request
|
||||
to create, update, or delete metadata does not affect those items.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Create container metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: MarkTwain" -H "X-Container-Meta-Web-Directory-Type: text/directory" -H "X-Container-Meta-Century: Nineteenth"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx05dbd434c651429193139-0052d82635
|
||||
Date: Thu, 16 Jan 2014 18:34:29 GMT
|
||||
|
||||
|
||||
- Update container metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: SamuelClemens"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: txe60c7314bf614bb39dfe4-0052d82653
|
||||
Date: Thu, 16 Jan 2014 18:34:59 GMT
|
||||
|
||||
|
||||
- Delete container metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Remove-Container-Meta-Century: x"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx7997e18da2a34a9e84ceb-0052d826d0
|
||||
Date: Thu, 16 Jan 2014 18:37:04 GMT
|
||||
|
||||
|
||||
If the request succeeds, the operation returns the ``No Content
|
||||
(204)`` response code.
|
||||
|
||||
To confirm your changes, issue a show container metadata request.
|
||||
|
||||
Error response codes:204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- X-Container-Read: X-Container-Read
|
||||
- X-Remove-Container-name: X-Remove-Container-name
|
||||
- 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-Remove-Versions-Location: X-Remove-Versions-Location
|
||||
- X-Container-Meta-name: X-Container-Meta-name
|
||||
- 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
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Date: Date
|
||||
- X-Timestamp: X-Timestamp
|
||||
- Content-Length: Content-Length
|
||||
- Content-Type: Content-Type
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Show container metadata
|
||||
=======================
|
||||
|
||||
.. rest_method:: HEAD /v1/{account}/{container}
|
||||
|
||||
Shows container metadata, including the number of objects and the total bytes of all objects stored in the container.
|
||||
|
||||
Show container metadata request:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain -X HEAD -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
X-Container-Object-Count: 1
|
||||
Accept-Ranges: bytes
|
||||
X-Container-Meta-Book: TomSawyer
|
||||
X-Timestamp: 1389727543.65372
|
||||
X-Container-Meta-Author: SamuelClemens
|
||||
X-Container-Bytes-Used: 14
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
|
||||
Date: Thu, 16 Jan 2014 18:37:22 GMT
|
||||
|
||||
|
||||
If the request succeeds, the operation returns the ``No Content
|
||||
(204)`` response code.
|
||||
|
||||
Error response codes:204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-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
|
||||
|
||||
|
||||
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
|
||||
- X-Container-Object-Count: X-Container-Object-Count
|
||||
- X-Container-Write: X-Container-Write
|
||||
- X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
|
||||
- Accept-Ranges: Accept-Ranges
|
||||
- X-Container-Read: X-Container-Read
|
||||
- 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
|
||||
- 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
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Delete container
|
||||
================
|
||||
|
||||
.. rest_method:: DELETE /v1/{account}/{container}
|
||||
|
||||
Deletes an empty container.
|
||||
|
||||
This operation fails unless the container is empty. An empty
|
||||
container has no objects.
|
||||
|
||||
Delete the ``steven`` container:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/steven -X DELETE -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
If the container does not exist, the response is:
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 404 Not Found
|
||||
Content-Length: 70
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx4d728126b17b43b598bf7-0052d81e34
|
||||
Date: Thu, 16 Jan 2014 18:00:20 GMT
|
||||
|
||||
|
||||
If the container exists and the deletion succeeds, the response is:
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14
|
||||
Date: Thu, 16 Jan 2014 18:04:04 GMT
|
||||
|
||||
|
||||
If the container exists but is not empty, the response is:
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 409 Conflict
|
||||
Content-Length: 95
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx7782dc6a97b94a46956b5-0052d81f6b
|
||||
Date: Thu, 16 Jan 2014 18:05:31 GMT
|
||||
<html>
|
||||
<h1>Conflict
|
||||
</h1>
|
||||
<p>There was a conflict when trying to complete your request.
|
||||
</p>
|
||||
</html>
|
||||
|
||||
Error response codes:404,204,409,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- 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-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Date: Date
|
||||
- X-Timestamp: X-Timestamp
|
||||
- Content-Length: Content-Length
|
||||
- Content-Type: Content-Type
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
687
api-ref/source/storage-object-services.inc
Normal file
687
api-ref/source/storage-object-services.inc
Normal file
@ -0,0 +1,687 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
=======
|
||||
Objects
|
||||
=======
|
||||
|
||||
Creates, replaces, shows details for, and deletes objects. Copies
|
||||
objects from another object with a new or different name. Updates
|
||||
object metadata.
|
||||
|
||||
|
||||
Get object content and metadata
|
||||
===============================
|
||||
|
||||
.. rest_method:: GET /v1/{account}/{container}/{object}
|
||||
|
||||
Downloads the object content and gets the object metadata.
|
||||
|
||||
This operation returns the object metadata in the response headers
|
||||
and the object content in the response body.
|
||||
|
||||
If this is a large object, the response body contains the
|
||||
concatenated content of the segment objects. To get the manifest
|
||||
instead of concatenated segment objects for a static large object,
|
||||
use the ``multipart-manifest`` query parameter.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Show object details for the ``goodbye`` object in the
|
||||
``marktwain`` container:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain/goodbye -X GET -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Length: 14
|
||||
Accept-Ranges: bytes
|
||||
Last-Modified: Wed, 15 Jan 2014 16:41:49 GMT
|
||||
Etag: 451e372e48e0f6b1114fa0724aa79fa1
|
||||
X-Timestamp: 1389804109.39027
|
||||
X-Object-Meta-Orig-Filename: goodbyeworld.txt
|
||||
Content-Type: application/octet-stream
|
||||
X-Trans-Id: tx8145a190241f4cf6b05f5-0052d82a34
|
||||
Date: Thu, 16 Jan 2014 18:51:32 GMT
|
||||
Goodbye World!
|
||||
|
||||
|
||||
- Show object details for the ``goodbye`` object, which does not
|
||||
exist, in the ``janeausten`` container:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/janeausten/goodbye -X GET -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 404 Not Found
|
||||
Content-Length: 70
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx073f7cbb850c4c99934b9-0052d82b04
|
||||
Date: Thu, 16 Jan 2014 18:55:00 GMT
|
||||
<html>
|
||||
<h1>Not Found
|
||||
</h1>
|
||||
<p>The resource could not be found.
|
||||
</p>
|
||||
</html>
|
||||
|
||||
|
||||
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,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- object: object
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- X-Newest: X-Newest
|
||||
- temp_url_sig: temp_url_sig
|
||||
- temp_url_expires: temp_url_expires
|
||||
- filename: filename
|
||||
- multipart-manifest: multipart-manifest
|
||||
- Range: Range
|
||||
- If-Match: If-Match
|
||||
- If-None-Match: If-None-Match
|
||||
- If-Modified-Since: If-Modified-Since
|
||||
- If-Unmodified-Since: If-Unmodified-Since
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
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
|
||||
- X-Delete-At: X-Delete-At
|
||||
- Accept-Ranges: Accept-Ranges
|
||||
- X-Object-Manifest: X-Object-Manifest
|
||||
- Last-Modified: Last-Modified
|
||||
- ETag: ETag
|
||||
- X-Timestamp: X-Timestamp
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
- Date: Date
|
||||
- X-Static-Large-Object: X-Static-Large-Object
|
||||
- Content-Type: Content-Type
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
See examples above.
|
||||
|
||||
|
||||
Create or replace object
|
||||
========================
|
||||
|
||||
.. rest_method:: PUT /v1/{account}/{container}/{object}
|
||||
|
||||
Creates an object with data content and metadata, or replaces an existing object with data content and metadata.
|
||||
|
||||
The PUT 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
|
||||
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.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Create object:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/janeausten/helloworld.txt -X PUT -H "Content-Length: 1" -H "Content-Type: text/html; charset=UTF-8" -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
|
||||
Content-Length: 116
|
||||
Etag: d41d8cd98f00b204e9800998ecf8427e
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
|
||||
Date: Fri, 17 Jan 2014 17:28:35 GMT
|
||||
|
||||
|
||||
- Replace object:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/janeausten/helloworld -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
|
||||
Content-Length: 116
|
||||
Etag: d41d8cd98f00b204e9800998ecf8427e
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
|
||||
Date: Fri, 17 Jan 2014 17:28:35 GMT
|
||||
|
||||
|
||||
The ``Created (201)`` response code indicates a successful write.
|
||||
|
||||
If the request times out, the operation returns the ``Request
|
||||
Timeout (408)`` response code.
|
||||
|
||||
The ``Length Required (411)`` response code indicates a missing
|
||||
``Transfer-Encoding`` or ``Content-Length`` request header.
|
||||
|
||||
If the MD5 checksum of the data that is written to the object store
|
||||
does not match the optional ``ETag`` value, the operation returns
|
||||
the ``Unprocessable Entity (422)`` response code.
|
||||
|
||||
Error response codes:201,422,411,408,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- object: object
|
||||
- container: container
|
||||
- multipart-manifest: multipart-manifest
|
||||
- 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
|
||||
- Transfer-Encoding: Transfer-Encoding
|
||||
- Content-Type: Content-Type
|
||||
- X-Detect-Content-Type: X-Detect-Content-Type
|
||||
- X-Copy-From: X-Copy-From
|
||||
- ETag: ETag
|
||||
- Content-Disposition: Content-Disposition
|
||||
- Content-Encoding: Content-Encoding
|
||||
- X-Delete-At: X-Delete-At
|
||||
- X-Delete-After: X-Delete-After
|
||||
- X-Object-Meta-name: X-Object-Meta-name
|
||||
- If-None-Match: If-None-Match
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Content-Length: Content-Length
|
||||
- ETag: ETag
|
||||
- X-Timestamp: X-Timestamp
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
- Date: Date
|
||||
- Content-Type: Content-Type
|
||||
- last_modified: last_modified
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Copy object
|
||||
===========
|
||||
|
||||
.. rest_method:: COPY /v1/{account}/{container}/{object}
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Copy the ``goodbye`` object from the ``marktwain`` container to
|
||||
the ``janeausten`` container:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain/goodbye -X COPY -H "X-Auth-Token: $token" -H "Destination: janeausten/goodbye"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Content-Length: 0
|
||||
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
|
||||
X-Copied-From: marktwain/goodbye
|
||||
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
|
||||
Etag: 451e372e48e0f6b1114fa0724aa79fa1
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Object-Meta-Movie: AmericanPie
|
||||
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
|
||||
Date: Fri, 17 Jan 2014 18:22:57 GMT
|
||||
|
||||
|
||||
- Alternatively, you can use PUT to copy the ``goodbye`` object from
|
||||
the ``marktwain`` container to the ``janeausten`` container. This
|
||||
request requires a ``Content-Length`` header, even if it is set
|
||||
to zero (0).
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/janeausten/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Copy-From: /marktwain/goodbye" -H "Content-Length: 0"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Content-Length: 0
|
||||
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
|
||||
X-Copied-From: marktwain/goodbye
|
||||
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
|
||||
Etag: 451e372e48e0f6b1114fa0724aa79fa1
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Object-Meta-Movie: AmericanPie
|
||||
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
|
||||
Date: Fri, 17 Jan 2014 18:22:57 GMT
|
||||
|
||||
|
||||
When several replicas exist, the system copies from the most recent
|
||||
replica. That is, the COPY operation behaves as though the
|
||||
``X-Newest`` header is in the request.
|
||||
|
||||
Error response codes:201,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- object: object
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- Destination: Destination
|
||||
- Content-Type: Content-Type
|
||||
- Content-Encoding: Content-Encoding
|
||||
- Content-Disposition: Content-Disposition
|
||||
- X-Object-Meta-name: X-Object-Meta-name
|
||||
- X-Fresh-Metadata: X-Fresh-Metadata
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Content-Length: Content-Length
|
||||
- X-Object-Meta-name: X-Object-Meta-name
|
||||
- X-Copied-From-Last-Modified: X-Copied-From-Last-Modified
|
||||
- X-Copied-From: X-Copied-From
|
||||
- Last-Modified: Last-Modified
|
||||
- ETag: ETag
|
||||
- X-Timestamp: X-Timestamp
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
- Date: Date
|
||||
- Content-Type: Content-Type
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Delete object
|
||||
=============
|
||||
|
||||
.. rest_method:: DELETE /v1/{account}/{container}/{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``
|
||||
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
|
||||
deletes the manifest object.
|
||||
|
||||
Example request and response:
|
||||
|
||||
- Delete the ``helloworld`` object from the ``marktwain`` container:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain/helloworld -X DELETE -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
Content-Length: 0
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac
|
||||
Date: Wed, 15 Jan 2014 21:29:16 GMT
|
||||
|
||||
|
||||
Typically, the DELETE operation does not return a response body.
|
||||
However, with the ``multipart-manifest=delete`` query parameter,
|
||||
the response body contains a list of manifest and segment objects
|
||||
and the status of their DELETE operations.
|
||||
|
||||
Error response codes:204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- object: object
|
||||
- container: container
|
||||
- multipart-manifest: multipart-manifest
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Date: Date
|
||||
- X-Timestamp: X-Timestamp
|
||||
- Content-Length: Content-Length
|
||||
- Content-Type: Content-Type
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Show object metadata
|
||||
====================
|
||||
|
||||
.. rest_method:: HEAD /v1/{account}/{container}/{object}
|
||||
|
||||
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:
|
||||
|
||||
- Show object metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain/goodbye -X HEAD -H "X-Auth-Token: $token"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Length: 14
|
||||
Accept-Ranges: bytes
|
||||
Last-Modified: Thu, 16 Jan 2014 21:12:31 GMT
|
||||
Etag: 451e372e48e0f6b1114fa0724aa79fa1
|
||||
X-Timestamp: 1389906751.73463
|
||||
X-Object-Meta-Book: GoodbyeColumbus
|
||||
Content-Type: application/octet-stream
|
||||
X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
|
||||
Date: Thu, 16 Jan 2014 21:13:19 GMT
|
||||
|
||||
|
||||
If the request succeeds, the operation returns the ``200`` response
|
||||
code.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:204,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- object: object
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-Token
|
||||
- temp_url_sig: temp_url_sig
|
||||
- temp_url_expires: temp_url_expires
|
||||
- filename: filename
|
||||
- X-Newest: X-Newest
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Last-Modified: Last-Modified
|
||||
- Content-Length: Content-Length
|
||||
- X-Object-Meta-name: X-Object-Meta-name
|
||||
- Content-Disposition: Content-Disposition
|
||||
- Content-Encoding: Content-Encoding
|
||||
- X-Delete-At: X-Delete-At
|
||||
- X-Object-Manifest: X-Object-Manifest
|
||||
- Last-Modified: Last-Modified
|
||||
- ETag: ETag
|
||||
- X-Timestamp: X-Timestamp
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
- Date: Date
|
||||
- X-Static-Large-Object: X-Static-Large-Object
|
||||
- Content-Type: Content-Type
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
See examples above.
|
||||
|
||||
|
||||
|
||||
Create or update object metadata
|
||||
================================
|
||||
|
||||
.. rest_method:: POST /v1/{account}/{container}/{object}
|
||||
|
||||
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
|
||||
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
|
||||
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)
|
||||
object.
|
||||
|
||||
A POST request deletes any existing custom metadata that you added
|
||||
with a previous PUT or POST request. Consequently, you must specify
|
||||
all custom metadata in the request. However, system metadata is
|
||||
unchanged by the POST request unless you explicitly supply it in a
|
||||
request header.
|
||||
|
||||
You can also set the ``X-Delete-At`` or ``X-Delete-After`` header
|
||||
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.
|
||||
|
||||
You can also use the `form POST feature
|
||||
<http://docs.openstack.org/liberty/config-reference/content/object-
|
||||
storage-form-post.html>`_ to upload objects.
|
||||
|
||||
Example requests and responses:
|
||||
|
||||
- Create object metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "X-Object-Meta-Book: GoodbyeColumbus"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 202 Accepted
|
||||
Content-Length: 76
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f
|
||||
Date: Thu, 16 Jan 2014 21:12:31 GMT
|
||||
<html>
|
||||
<h1>Accepted
|
||||
</h1>
|
||||
<p>The request is accepted for processing.
|
||||
</p>
|
||||
</html>
|
||||
|
||||
|
||||
- Update object metadata:
|
||||
|
||||
::
|
||||
|
||||
curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" H "X-Object-Meta-Book: GoodbyeOldFriend"
|
||||
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
HTTP/1.1 202 Accepted
|
||||
Content-Length: 76
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
|
||||
Date: Thu, 16 Jan 2014 21:18:28 GMT
|
||||
<html>
|
||||
<h1>Accepted
|
||||
</h1>
|
||||
<p>The request is accepted for processing.
|
||||
</p>
|
||||
</html>
|
||||
|
||||
Error response codes:202,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- account: account
|
||||
- object: object
|
||||
- container: container
|
||||
- X-Auth-Token: X-Auth-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
|
||||
- X-Trans-Id-Extra: X-Trans-Id-Extra
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- Date: Date
|
||||
- X-Timestamp: X-Timestamp
|
||||
- Content-Length: Content-Length
|
||||
- Content-Type: Content-Type
|
||||
- X-Trans-Id: X-Trans-Id
|
||||
|
||||
|
||||
|
||||
|
||||
37
api-ref/source/storage_endpoints.inc
Normal file
37
api-ref/source/storage_endpoints.inc
Normal file
@ -0,0 +1,37 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
=========
|
||||
Endpoints
|
||||
=========
|
||||
|
||||
If configured, lists endpoints for an account.
|
||||
|
||||
|
||||
List endpoints
|
||||
==============
|
||||
|
||||
.. rest_method:: GET /v1/endpoints
|
||||
|
||||
Lists endpoints for an object, account, or container.
|
||||
|
||||
When the cloud provider enables middleware to list the
|
||||
``/endpoints/`` path, software that needs data location information
|
||||
can use this call to avoid network overhead. The cloud provider can
|
||||
map the ``/endpoints/`` path to another resource, so this exact
|
||||
resource might vary from provider to provider. Because it goes
|
||||
straight to the middleware, the call is not authenticated, so be
|
||||
sure you have tightly secured the environment and network when
|
||||
using this call.
|
||||
|
||||
Error response codes:201,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
This operation does not accept a request body.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
41
api-ref/source/storage_info.inc
Normal file
41
api-ref/source/storage_info.inc
Normal file
@ -0,0 +1,41 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
===============
|
||||
Discoverability
|
||||
===============
|
||||
|
||||
If configured, lists the activated capabilities for this version of
|
||||
the OpenStack Object Storage API.
|
||||
|
||||
|
||||
List activated capabilities
|
||||
===========================
|
||||
|
||||
.. rest_method:: GET /info
|
||||
|
||||
Lists the activated capabilities for this version of the OpenStack Object Storage API.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- swiftinfo_sig: swiftinfo_sig
|
||||
- swiftinfo_expires: swiftinfo_expires
|
||||
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/capabilities-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
@ -10,6 +10,7 @@ nosexcover
|
||||
nosehtmloutput
|
||||
oslosphinx
|
||||
sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 # BSD
|
||||
os-api-ref>=0.1.0 # Apache-2.0
|
||||
os-testr>=0.4.1
|
||||
mock>=1.0
|
||||
python-swiftclient
|
||||
|
||||
16
tox.ini
16
tox.ini
@ -59,6 +59,22 @@ commands = {posargs}
|
||||
[testenv:docs]
|
||||
commands = python setup.py build_sphinx
|
||||
|
||||
[testenv:api-ref]
|
||||
# This environment is called from CI scripts to test and publish
|
||||
# the API Ref to developer.openstack.org.
|
||||
# NOTE(sdague): this target does not use constraints because
|
||||
# upstream infra does not yet support it. Once that's fixed, we can
|
||||
# drop the install_command.
|
||||
#
|
||||
# we do not use -W here because we are doing some slightly tricky
|
||||
# things to build a single page document, and as such, we are ok
|
||||
# ignoring the duplicate stanzas warning.
|
||||
install_command = pip install -U --force-reinstall {opts} {packages}
|
||||
commands =
|
||||
rm -rf api-ref/build
|
||||
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
|
||||
|
||||
|
||||
[testenv:bandit]
|
||||
deps = -r{toxinidir}/test-requirements.txt
|
||||
commands = bandit -c bandit.yaml -r swift bin -n 5 -p gate
|
||||
|
||||
Loading…
Reference in New Issue
Block a user