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
|
nosehtmloutput
|
||||||
oslosphinx
|
oslosphinx
|
||||||
sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 # BSD
|
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
|
os-testr>=0.4.1
|
||||||
mock>=1.0
|
mock>=1.0
|
||||||
python-swiftclient
|
python-swiftclient
|
||||||
|
|||||||
16
tox.ini
16
tox.ini
@ -59,6 +59,22 @@ commands = {posargs}
|
|||||||
[testenv:docs]
|
[testenv:docs]
|
||||||
commands = python setup.py build_sphinx
|
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]
|
[testenv:bandit]
|
||||||
deps = -r{toxinidir}/test-requirements.txt
|
deps = -r{toxinidir}/test-requirements.txt
|
||||||
commands = bandit -c bandit.yaml -r swift bin -n 5 -p gate
|
commands = bandit -c bandit.yaml -r swift bin -n 5 -p gate
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user