"Fossies" - the Fresh Open Source Software Archive

Member "swift-2.21.0/api-ref/source/storage-container-services.inc" (25 Mar 2019, 15676 Bytes) of package /linux/misc/openstack/swift-2.21.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) fasm source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "storage-container-services.inc" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.19.1_vs_2.21.0.

    1 .. -*- rst -*-
    2 
    3 ==========
    4 Containers
    5 ==========
    6 
    7 Lists objects in a container. Creates, shows details for, and
    8 deletes containers. Creates, updates, shows, and deletes container
    9 metadata. For more information and concepts about
   10 containers see `Object Storage API overview
   11 <https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html>`_.
   12 
   13 
   14 Show container details and list objects
   15 =======================================
   16 
   17 .. rest_method::  GET /v1/{account}/{container}
   18 
   19 Shows details for a container and lists objects, sorted by name, in the container.
   20 
   21 Specify query parameters in the request to filter the list and
   22 return a subset of objects. Omit query parameters to return
   23 a list of objects that are stored in the container,
   24 up to 10,000 names. The 10,000 maximum value is configurable. To
   25 view the value for the cluster, issue a GET ``/info`` request.
   26 
   27 Example requests and responses:
   28 
   29 - ``OK (200)``. Success. The response body lists the objects.
   30 
   31 - ``No Content (204)``. Success. The response body shows no objects.
   32   Either the container has no objects or you are paging through a
   33   long list of objects by using the ``marker``, ``limit``, or
   34   ``end_marker`` query parameter and you have reached the end of
   35   the list.
   36 
   37 If the container does not exist, the call returns the ``Not Found
   38 (404)`` response code.
   39 
   40 Normal response codes: 200, 204
   41 
   42 Error response codes: 404
   43 
   44 
   45 Request
   46 -------
   47 
   48 .. rest_parameters:: parameters.yaml
   49 
   50    - account: account
   51    - container: container
   52    - limit: limit
   53    - marker: marker
   54    - end_marker: end_marker
   55    - prefix: prefix
   56    - format: format
   57    - delimiter: delimiter
   58    - path: path
   59    - X-Auth-Token: X-Auth-Token
   60    - X-Service-Token: X-Service-Token
   61    - X-Newest: X-Newest
   62    - Accept: Accept
   63    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key_req
   64    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2_req
   65    - X-Trans-Id-Extra: X-Trans-Id-Extra
   66    - X-Storage-Policy: X-Storage-Policy
   67 
   68 
   69 Response Parameters
   70 -------------------
   71 
   72 .. rest_parameters:: parameters.yaml
   73 
   74    - X-Container-Meta-name: X-Container-Meta-name
   75    - Content-Length: Content-Length_listing_resp
   76    - X-Container-Object-Count: X-Container-Object-Count
   77    - X-Container-Bytes-Used: X-Container-Bytes-Used
   78    - Accept-Ranges: Accept-Ranges
   79    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key_resp
   80    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2_resp
   81    - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count_resp
   82    - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes_resp
   83    - X-Storage-Policy: X-Storage-Policy
   84    - X-Container-Read: X-Container-Read_resp
   85    - X-Container-Write: X-Container-Write_resp
   86    - X-Container-Sync-Key: X-Container-Sync-Key_resp
   87    - X-Container-Sync-To: X-Container-Sync-To_resp
   88    - X-Versions-Location: X-Versions-Location_resp
   89    - X-History-Location: X-History-Location_resp
   90    - X-Timestamp: X-Timestamp
   91    - X-Trans-Id: X-Trans-Id
   92    - X-Openstack-Request-Id: X-Openstack-Request-Id
   93    - Content-Type: Content-Type_listing_resp
   94    - Date: Date
   95    - hash: hash
   96    - last_modified: last_modified
   97    - content_type: content_type
   98    - bytes: bytes_in_container_get
   99    - name: name_in_container_get
  100    - symlink_path: symlink_path
  101 
  102 
  103 Response Example format=json
  104 ----------------------------
  105 
  106 .. literalinclude:: samples/objects-list-http-response-json.txt
  107 .. literalinclude:: samples/objects-list-response.json
  108 
  109 
  110 Response Example format=xml
  111 ---------------------------
  112 
  113 .. literalinclude:: samples/objects-list-http-response-xml.txt
  114 .. literalinclude:: samples/objects-list-response.xml
  115 
  116 Create container
  117 ================
  118 
  119 .. rest_method::  PUT /v1/{account}/{container}
  120 
  121 Creates a container.
  122 
  123 You do not need to check whether a container already exists before
  124 issuing a PUT operation because the operation is idempotent: It
  125 creates a container or updates an existing container, as
  126 appropriate.
  127 
  128 To create, update, or delete a custom metadata item, use the ``X
  129 -Container-Meta-{name}`` header, where ``{name}`` is the name of
  130 the metadata item.
  131 
  132 .. include:: metadata_header_syntax.inc
  133 .. include:: metadata_header_encoding.inc
  134 
  135 Example requests and responses:
  136 
  137 - Create a container with no metadata:
  138 
  139   ::
  140 
  141      curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
  142 
  143 
  144 
  145 
  146   ::
  147 
  148      HTTP/1.1 201 Created
  149      Content-Length: 0
  150      Content-Type: text/html; charset=UTF-8
  151      X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
  152      X-Openstack-Request-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
  153      Date: Tue, 14 Jan 2014 19:09:10 GMT
  154 
  155 
  156 - Create a container with metadata:
  157 
  158   ::
  159 
  160      curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer"
  161 
  162 
  163 
  164 
  165   ::
  166 
  167      HTTP/1.1 201 Created
  168      Content-Length: 0
  169      Content-Type: text/html; charset=UTF-8
  170      X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
  171      X-Openstack-Request-Id: tx06021f10fc8642b2901e7-0052d58f37
  172      Date: Tue, 14 Jan 2014 19:25:43 GMT
  173 
  174 - Create a container with an ACL to allow anybody to get an object in the
  175   marktwain container:
  176   ::
  177 
  178      curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Read: .r:*"
  179 
  180 
  181 
  182   ::
  183 
  184      HTTP/1.1 201 Created
  185      Content-Length: 0
  186      Content-Type: text/html; charset=UTF-8
  187      X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
  188      X-Openstack-Request-Id: tx06021f10fc8642b2901e7-0052d58f37
  189      Date: Tue, 14 Jan 2014 19:25:43 GMT
  190 
  191 Normal response codes: 201, 202
  192 
  193 Error response codes: 400, 404, 507
  194 
  195 Request
  196 -------
  197 
  198 .. rest_parameters:: parameters.yaml
  199 
  200    - account: account
  201    - container: container
  202    - X-Auth-Token: X-Auth-Token
  203    - X-Service-Token: X-Service-Token
  204    - X-Container-Read: X-Container-Read
  205    - X-Container-Write: X-Container-Write
  206    - X-Container-Sync-To: X-Container-Sync-To
  207    - X-Container-Sync-Key: X-Container-Sync-Key
  208    - X-Versions-Location: X-Versions-Location
  209    - X-History-Location: X-History-Location
  210    - X-Container-Meta-name: X-Container-Meta-name_req
  211    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
  212    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
  213    - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
  214    - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
  215    - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
  216    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key_req
  217    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2_req
  218    - X-Trans-Id-Extra: X-Trans-Id-Extra
  219    - X-Storage-Policy: X-Storage-Policy
  220 
  221 
  222 Response Parameters
  223 -------------------
  224 
  225 .. rest_parameters:: parameters.yaml
  226 
  227    - Date: Date
  228    - X-Timestamp: X-Timestamp
  229    - Content-Length: Content-Length_cud_resp
  230    - Content-Type: Content-Type_cud_resp
  231    - X-Trans-Id: X-Trans-Id
  232    - X-Openstack-Request-Id: X-Openstack-Request-Id
  233 
  234 
  235 
  236 
  237 
  238 
  239 Create, update, or delete container metadata
  240 ============================================
  241 
  242 .. rest_method::  POST /v1/{account}/{container}
  243 
  244 Creates, updates, or deletes custom metadata for a container.
  245 
  246 To create, update, or delete a custom metadata item, use the ``X
  247 -Container-Meta-{name}`` header, where ``{name}`` is the name of
  248 the metadata item.
  249 
  250 .. include:: metadata_header_syntax.inc
  251 .. include:: metadata_header_encoding.inc
  252 
  253 Subsequent requests for the same key and value pair overwrite the
  254 previous value.
  255 
  256 To delete container metadata, send an empty value for that header,
  257 such as for the ``X-Container-Meta-Book`` header. If the tool you
  258 use to communicate with Object Storage, such as an older version of
  259 cURL, does not support empty headers, send the ``X-Remove-
  260 Container-Meta-{name}`` header with an arbitrary value. For
  261 example, ``X-Remove-Container-Meta-Book: x``. The operation ignores
  262 the arbitrary value.
  263 
  264 If the container already has other custom metadata items, a request
  265 to create, update, or delete metadata does not affect those items.
  266 
  267 Example requests and responses:
  268 
  269 - Create container metadata:
  270 
  271   ::
  272 
  273      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"
  274 
  275 
  276 
  277 
  278   ::
  279 
  280      HTTP/1.1 204 No Content
  281      Content-Length: 0
  282      Content-Type: text/html; charset=UTF-8
  283      X-Trans-Id: tx05dbd434c651429193139-0052d82635
  284      X-Openstack-Request-Id: tx05dbd434c651429193139-0052d82635
  285      Date: Thu, 16 Jan 2014 18:34:29 GMT
  286 
  287 
  288 - Update container metadata:
  289 
  290   ::
  291 
  292      curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: SamuelClemens"
  293 
  294 
  295 
  296 
  297   ::
  298 
  299      HTTP/1.1 204 No Content
  300      Content-Length: 0
  301      Content-Type: text/html; charset=UTF-8
  302      X-Trans-Id: txe60c7314bf614bb39dfe4-0052d82653
  303      X-Openstack-Request-Id: txe60c7314bf614bb39dfe4-0052d82653
  304      Date: Thu, 16 Jan 2014 18:34:59 GMT
  305 
  306 
  307 - Delete container metadata:
  308 
  309   ::
  310 
  311      curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Remove-Container-Meta-Century: x"
  312 
  313 
  314 
  315 
  316   ::
  317 
  318      HTTP/1.1 204 No Content
  319      Content-Length: 0
  320      Content-Type: text/html; charset=UTF-8
  321      X-Trans-Id: tx7997e18da2a34a9e84ceb-0052d826d0
  322      X-Openstack-Request-Id: tx7997e18da2a34a9e84ceb-0052d826d0
  323      Date: Thu, 16 Jan 2014 18:37:04 GMT
  324 
  325 
  326 If the request succeeds, the operation returns the ``No Content
  327 (204)`` response code.
  328 
  329 To confirm your changes, issue a show container metadata request.
  330 
  331 Normal response codes: 204
  332 
  333 Error response codes: 404
  334 
  335 
  336 Request
  337 -------
  338 
  339 .. rest_parameters:: parameters.yaml
  340 
  341    - account: account
  342    - container: container
  343    - X-Auth-Token: X-Auth-Token
  344    - X-Service-Token: X-Service-Token
  345    - X-Container-Read: X-Container-Read
  346    - X-Remove-Container-name: X-Remove-Container-name
  347    - X-Container-Write: X-Container-Write
  348    - X-Container-Sync-To: X-Container-Sync-To
  349    - X-Container-Sync-Key: X-Container-Sync-Key
  350    - X-Versions-Location: X-Versions-Location
  351    - X-History-Location: X-History-Location
  352    - X-Remove-Versions-Location: X-Remove-Versions-Location
  353    - X-Remove-History-Location: X-Remove-History-Location
  354    - X-Container-Meta-name: X-Container-Meta-name_req
  355    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
  356    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
  357    - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
  358    - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
  359    - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
  360    - X-Container-Meta-Web-Directory-Type: X-Container-Meta-Web-Directory-Type
  361    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key_req
  362    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2_req
  363    - X-Trans-Id-Extra: X-Trans-Id-Extra
  364 
  365 
  366 Response Parameters
  367 -------------------
  368 
  369 .. rest_parameters:: parameters.yaml
  370 
  371    - Date: Date
  372    - X-Timestamp: X-Timestamp
  373    - Content-Length: Content-Length_cud_resp
  374    - Content-Type: Content-Type_cud_resp
  375    - X-Trans-Id: X-Trans-Id
  376    - X-Openstack-Request-Id: X-Openstack-Request-Id
  377 
  378 
  379 
  380 
  381 
  382 Show container metadata
  383 =======================
  384 
  385 .. rest_method::  HEAD /v1/{account}/{container}
  386 
  387 Shows container metadata, including the number of objects and the total bytes of all objects stored in the container.
  388 
  389 Show container metadata request:
  390 
  391 ::
  392 
  393    curl -i $publicURL/marktwain -X HEAD -H "X-Auth-Token: $token"
  394 
  395 
  396 
  397 
  398 ::
  399 
  400    HTTP/1.1 204 No Content
  401    Content-Length: 0
  402    X-Container-Object-Count: 1
  403    Accept-Ranges: bytes
  404    X-Container-Meta-Book: TomSawyer
  405    X-Timestamp: 1389727543.65372
  406    X-Container-Meta-Author: SamuelClemens
  407    X-Container-Bytes-Used: 14
  408    Content-Type: text/plain; charset=utf-8
  409    X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
  410    X-Openstack-Request-Id: tx0287b982a268461b9ec14-0052d826e2
  411    Date: Thu, 16 Jan 2014 18:37:22 GMT
  412 
  413 
  414 If the request succeeds, the operation returns the ``No Content
  415 (204)`` response code.
  416 
  417 Normal response codes: 204
  418 
  419 
  420 Request
  421 -------
  422 
  423 .. rest_parameters:: parameters.yaml
  424 
  425    - account: account
  426    - container: container
  427    - X-Auth-Token: X-Auth-Token
  428    - X-Service-Token: X-Service-Token
  429    - X-Newest: X-Newest
  430    - X-Trans-Id-Extra: X-Trans-Id-Extra
  431 
  432 
  433 Response Parameters
  434 -------------------
  435 
  436 .. rest_parameters:: parameters.yaml
  437 
  438    - X-Container-Meta-name: X-Container-Meta-name
  439    - Content-Length: Content-Length_cud_resp
  440    - X-Container-Object-Count: X-Container-Object-Count
  441    - X-Container-Bytes-Used: X-Container-Bytes-Used
  442    - X-Container-Write: X-Container-Write_resp
  443    - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes_resp
  444    - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count_resp
  445    - Accept-Ranges: Accept-Ranges
  446    - X-Container-Read: X-Container-Read_resp
  447    - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
  448    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key_resp
  449    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2_resp
  450    - X-Timestamp: X-Timestamp
  451    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
  452    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
  453    - X-Container-Sync-Key: X-Container-Sync-Key_resp
  454    - X-Container-Sync-To: X-Container-Sync-To_resp
  455    - Date: Date
  456    - X-Trans-Id: X-Trans-Id
  457    - X-Openstack-Request-Id: X-Openstack-Request-Id
  458    - Content-Type: Content-Type_cud_resp
  459    - X-Versions-Location: X-Versions-Location_resp
  460    - X-History-Location: X-History-Location_resp
  461    - X-Storage-Policy: X-Storage-Policy
  462 
  463 
  464 
  465 
  466 
  467 Delete container
  468 ================
  469 
  470 .. rest_method::  DELETE /v1/{account}/{container}
  471 
  472 Deletes an empty container.
  473 
  474 This operation fails unless the container is empty. An empty
  475 container has no objects.
  476 
  477 Delete the ``steven`` container:
  478 
  479 ::
  480 
  481    curl -i $publicURL/steven -X DELETE -H "X-Auth-Token: $token"
  482 
  483 
  484 If the container does not exist, the response is:
  485 
  486 ::
  487 
  488    HTTP/1.1 404 Not Found
  489    Content-Length: 70
  490    Content-Type: text/html; charset=UTF-8
  491    X-Trans-Id: tx4d728126b17b43b598bf7-0052d81e34
  492    X-Openstack-Request-Id: tx4d728126b17b43b598bf7-0052d81e34
  493    Date: Thu, 16 Jan 2014 18:00:20 GMT
  494 
  495 
  496 If the container exists and the deletion succeeds, the response is:
  497 
  498 ::
  499 
  500    HTTP/1.1 204 No Content
  501    Content-Length: 0
  502    Content-Type: text/html; charset=UTF-8
  503    X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14
  504    X-Openstack-Request-Id: txf76c375ebece4df19c84c-0052d81f14
  505    Date: Thu, 16 Jan 2014 18:04:04 GMT
  506 
  507 
  508 If the container exists but is not empty, the response is:
  509 
  510 ::
  511 
  512    HTTP/1.1 409 Conflict
  513    Content-Length: 95
  514    Content-Type: text/html; charset=UTF-8
  515    X-Trans-Id: tx7782dc6a97b94a46956b5-0052d81f6b
  516    X-Openstack-Request-Id: tx7782dc6a97b94a46956b5-0052d81f6b
  517    Date: Thu, 16 Jan 2014 18:05:31 GMT
  518    <html>
  519    <h1>Conflict
  520    </h1>
  521    <p>There was a conflict when trying to complete your request.
  522    </p>
  523    </html>
  524 
  525 Normal response codes: 204
  526 
  527 Error response codes: 404, 409
  528 
  529 
  530 Request
  531 -------
  532 
  533 .. rest_parameters:: parameters.yaml
  534 
  535    - account: account
  536    - container: container
  537    - X-Auth-Token: X-Auth-Token
  538    - X-Service-Token: X-Service-Token
  539    - X-Trans-Id-Extra: X-Trans-Id-Extra
  540 
  541 
  542 Response Parameters
  543 -------------------
  544 
  545 .. rest_parameters:: parameters.yaml
  546 
  547    - Date: Date
  548    - X-Timestamp: X-Timestamp
  549    - Content-Length: Content-Length_cud_resp
  550    - Content-Type: Content-Type_cud_resp
  551    - X-Trans-Id: X-Trans-Id
  552    - X-Openstack-Request-Id: X-Openstack-Request-Id
  553 
  554 
  555 
  556 
  557 
  558