upgrade object store docs

k0ka · Jan 30, 2024 · Jan 17, 2024 · Jan 17, 2024 · Jan 17, 2024 · Jan 17, 2024
commit 7af31ed010f355577b6037c74a5490f29d496926
diff --git a/doc/services/compute/v2/create.rst b/doc/services/compute/v2/create.rst
@@ -1,12 +1,3 @@
-Create Service
-==============
+.. |method| replace:: objectStoreV1
 
-In order to work with the service you have to :doc:`setup the client </setup>` first.
-
-Service can be created via ``blockStorageV3()`` method of the ``OpenStack`` object.
-
-.. sample:: BlockStorage/v3/create.php
-
-A list of additional options can be passed to the method. For example, to change the region:
-
-.. sample:: BlockStorage/v3/create_with_region.php
+.. include:: /common/create-service.rst
diff --git a/doc/services/object-store/v1/account.rst b/doc/services/object-store/v1/account.rst
@@ -1,19 +1,27 @@
 Account
 =======
 
-Show account details
---------------------
+Account represents the top-level of the hierarchy. Your service provider creates your account and you own all resources
+in that account. The account defines a namespace for containers. In the OpenStack environment, account is synonymous
+with a project or tenant.
+
+.. osdoc:: https://docs.openstack.org/api-ref/object-store/#accounts
+
+.. |models| replace:: accounts
+
+.. include:: /common/service.rst
+
+Read
+----
 
 To work with an Object Store account, you must first retrieve an account object like so:
 
-.. sample:: ObjectStore/v1/account/get.php
-.. refdoc:: OpenStack/ObjectStore/v1/Service.html#method_getAccount
+.. sample:: ObjectStore/v1/account/read.php
 
 Get account metadata
 --------------------
 
 .. sample:: ObjectStore/v1/account/get_metadata.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Account.html#method_getMetadata
 
 Replace all metadata with new values
 ------------------------------------
@@ -76,4 +84,3 @@ the metadata of the account will now be:
 To reset metadata, you must run:
 
 .. sample:: ObjectStore/v1/account/merge_metadata.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Account.html#method_mergeMetadata
diff --git a/doc/services/object-store/v1/containers.rst b/doc/services/object-store/v1/containers.rst
@@ -1,32 +1,39 @@
 Containers
 ==========
 
-Show details for a container
-----------------------------
+Container defines a namespace for objects. An object with the same name in two different containers represents
+two different objects.
 
-.. sample:: ObjectStore/v1/containers/get.php
-.. refdoc:: OpenStack/ObjectStore/v1/Service.html#method_getContainer
+.. osdoc:: https://docs.openstack.org/api-ref/object-store/#containers
 
-At this point, the object returned is *empty* because we did not execute a HTTP request to receive the state of the
-container from the API. This is in accordance with one of the SDK's general policies of not assuming too much at the
-expense of performance.
+.. |models| replace:: containers
 
-To synchronize the local object's state with the remote API, you can run:
+.. include:: /common/service.rst
 
-.. code-block:: php
+Read
+----
+
+.. sample:: ObjectStore/v1/containers/read.php
 
-    $container->retrieve();
+You can read the content of a container:
+
+.. code-block:: php
 
     printf("%s container has %d objects and %d bytes",
         $container->name, $container->objectCount, $container->bytesUsed);
 
-and all of the local properties will match those of the remote resource.
+Delete
+------
 
-List containers
----------------
+.. sample:: ObjectStore/v1/containers/delete.php
+
+The API will only accept DELETE requests on containers when they are empty. If you have a container with any objects
+inside, the operation will fail.
+
+List
+----
 
 .. sample:: ObjectStore/v1/containers/list.php
-.. refdoc:: OpenStack/ObjectStore/v1/Service.html#method_listContainers
 
 When listing containers, you must be aware that not *all* information about a container is returned in a collection.
 Very often only the object count, bytes used and container name will be exposed. If you would like to
@@ -43,20 +50,10 @@ container.
 
 .. include:: /common/generators.rst
 
-Delete container
-----------------
-
-.. sample:: ObjectStore/v1/containers/delete.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_delete
-
-The API will only accept DELETE requests on containers when they are empty. If you have a container with any objects
-inside, the operation will fail.
-
 Get metadata
 ------------
 
 .. sample:: ObjectStore/v1/containers/get_metadata.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_getMetadata
 
 The returned value will be a standard associative array, or hash, containing arbitrary key/value pairs. These will
 correspond to the values set either when the container was created, or when a previous ``mergeMetadata`` or
@@ -66,7 +63,6 @@ Replace all metadata with new values
 ------------------------------------
 
 .. sample:: ObjectStore/v1/containers/reset_metadata.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_resetMetadata
 
 In order to replace all existing metadata with a set of new values, you can use this operation. Any existing metadata
 items which not specified in the new set will be removed. For example, say an account has the following metadata
@@ -96,7 +92,6 @@ Merge new metadata values with existing
 ---------------------------------------
 
 .. sample:: ObjectStore/v1/containers/merge_metadata.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_mergeMetadata
 
 In order to merge a set of new metadata values with the existing metadata set, you can use this operation. Any existing
 metadata items which are not specified in the new set will be preserved. For example, say an account has the following

diff --git a/doc/services/object-store/v1/create.rst b/doc/services/object-store/v1/create.rst
@@ -0,0 +1,3 @@
+.. |method| replace::
+
+.. include:: /common/create-service.rst
diff --git a/doc/services/object-store/v1/index.rst b/doc/services/object-store/v1/index.rst
@@ -2,8 +2,9 @@ Object Store v1
 ===============
 
 .. toctree::
-   :maxdepth: 3
+    :maxdepth: 3
 
-   account
-   containers
-   objects
+    create
+    account
+    containers
+    objects
diff --git a/doc/services/object-store/v1/objects.rst b/doc/services/object-store/v1/objects.rst
@@ -1,48 +1,61 @@
 Objects
 =======
 
-Show details for an object
---------------------------
+Object stores data content, such as documents, images, and so on. You can also store custom metadata with an object.
 
-.. sample:: ObjectStore/v1/objects/get.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_getObject
+.. osdoc:: https://docs.openstack.org/api-ref/object-store/#objects
 
-At this point, the object returned is *empty* because we did not execute a HTTP request to receive the state of the
-container from the API. This is in accordance with one of the SDK's general policies of not assuming too much at the
-expense of performance.
+.. |models| replace:: objects
 
-To synchronize the local object's state with the remote API, you can run:
+.. include:: /common/service.rst
 
-.. code-block:: php
+Create
+------
 
-    $object->retrieve();
+When creating an object, you can upload its content according to a string representation:
 
-    printf("%s/%s is %d bytes long and was last modified on %s",
-        $object->containerName, $object->name, $object->contentLength, $object->lastModified);
+.. sample:: ObjectStore/v1/objects/create.php
 
-and all of the local properties will match those of the remote resource. The ``retrieve`` call, although fetching all
-of the object's metadata, will not download the object's content. To do this, see the next section.
+If that is not optimal or convenient, you can use a stream instead. Any instance of ``\Psr\Http\Message\StreamInterface``
+is acceptable. For example, to use a normal Guzzle stream:
 
-Download an object
-------------------
+.. sample:: ObjectStore/v1/objects/create_from_stream.php
 
-.. sample:: ObjectStore/v1/objects/download.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/StorageObject.html#method_download
+Create a large object (over 5GB)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As you will notice, a Stream_ object is returned by this call. For more information about dealing with streams, please
-consult `Guzzle's docs`_.
+For large objects (those over 5GB), you will need to use a concept in Swift called Dynamic Large Objects (DLO). When
+uploading, this is what happens under the hood:
 
-By default, the whole body of the object is fetched before the function returns, set the ``'requestOptions'`` key of
-parameter ``$data`` to ``['stream' => true]`` to get the stream before the end of download.
+1. The large file is separated into smaller segments
+2. Each segment is uploaded
+3. A manifest file is created which, when requested by clients, will concatenate all the segments as a single file
 
-.. _Stream: https://github.com/guzzle/streams/blob/master/src/Stream.php
-.. _Guzzle's docs: https://guzzle.readthedocs.org/en/5.3/streams.html
+To upload a DLO, you need to call:
 
-List objects
-------------
+.. sample:: ObjectStore/v1/objects/create_large_object.php
+
+Read
+----
+
+.. sample:: ObjectStore/v1/objects/read.php
+
+You can read properties of an object:
+
+.. code-block:: php
+
+    printf("%s/%s is %d bytes long and was last modified on %s",
+        $object->containerName, $object->name, $object->contentLength, $object->lastModified);
+
+Delete
+------
+
+.. sample:: ObjectStore/v1/objects/delete.php
+
+List
+----
 
 .. sample:: ObjectStore/v1/objects/list.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_listObjects
 
 When listing objects, you must be aware that not *all* information about a container is returned in a collection.
 Very often only the MD5 hash, last modified date, bytes used, content type and object name will be
@@ -59,51 +72,29 @@ If you have a large collection of $object, this will slow things down because yo
 
 .. include:: /common/generators.rst
 
-Create an object
-----------------
-
-When creating an object, you can upload its content according to a string representation:
-
-.. sample:: ObjectStore/v1/objects/create.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_createObject
-
-If that is not optimal or convenient, you can use a stream instead. Any instance of ``\Psr\Http\Message\StreamInterface``
-is acceptable. For example, to use a normal Guzzle stream:
-
-.. sample:: ObjectStore/v1/objects/create_from_stream.php
-
-Create a large object (over 5GB)
---------------------------------
+Download an object
+------------------
 
-For large objects (those over 5GB), you will need to use a concept in Swift called Dynamic Large Objects (DLO). When
-uploading, this is what happens under the hood:
+.. sample:: ObjectStore/v1/objects/download.php
 
-1. The large file is separated into smaller segments
-2. Each segment is uploaded
-3. A manifest file is created which, when requested by clients, will concatenate all the segments as a single file
+As you will notice, a Stream_ object is returned by this call. For more information about dealing with streams, please
+consult `Guzzle's docs`_.
 
-To upload a DLO, you need to call:
+By default, the whole body of the object is fetched before the function returns, set the ``'requestOptions'`` key of
+parameter ``$data`` to ``['stream' => true]`` to get the stream before the end of download.
 
-.. sample:: ObjectStore/v1/objects/create_large_object.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/Container.html#method_createLargeObject
+.. _Stream: https://github.com/guzzle/streams/blob/master/src/Stream.php
+.. _Guzzle's docs: https://guzzle.readthedocs.org/en/5.3/streams.html
 
 Copy object
 -----------
 
 .. sample:: ObjectStore/v1/objects/copy.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/StorageObject.html#method_copy
-
-Delete object
--------------
-
-.. sample:: ObjectStore/v1/objects/delete.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/StorageObject.html#method_delete
 
 Get metadata
 ------------
 
 .. sample:: ObjectStore/v1/objects/get_metadata.php
-.. refdoc:: OpenStack/ObjectStore/v1/Models/StorageObject.html#method_getMetadata
 
 The returned value will be a standard associative array, or hash, containing arbitrary key/value pairs. These will
 correspond to the values set either when the object was created, or when a previous ``mergeMetadata`` or

diff --git a/samples/ObjectStore/v1/account/get_metadata.php b/samples/ObjectStore/v1/account/get_metadata.php
@@ -9,7 +9,6 @@
         'id'       => '{userId}',
         'password' => '{password}'
     ],
-    'scope'   => ['project' => ['id' => '{projectId}']]
 ]);
 
 $service = $openstack->objectStoreV1();

diff --git a/samples/ObjectStore/v1/account/merge_metadata.php b/samples/ObjectStore/v1/account/merge_metadata.php
@@ -9,7 +9,6 @@
         'id'       => '{userId}',
         'password' => '{password}'
     ],
-    'scope'   => ['project' => ['id' => '{projectId}']]
 ]);
 
 $service = $openstack->objectStoreV1();

diff --git a/samples/ObjectStore/v1/account/get.php → samples/ObjectStore/v1/account/read.php b/samples/ObjectStore/v1/account/get.php → samples/ObjectStore/v1/account/read.php
@@ -9,8 +9,7 @@
         'id'       => '{userId}',
         'password' => '{password}'
     ],
-    'scope'   => ['project' => ['id' => '{projectId}']]
 ]);
 
-$account = $openstack->objectStoreV1()
-                     ->getAccount();
+$service = $openstack->objectStoreV1();
+$account = $service->getAccount();
diff --git a/samples/ObjectStore/v1/account/reset_metadata.php b/samples/ObjectStore/v1/account/reset_metadata.php
@@ -9,11 +9,9 @@
         'id'       => '{userId}',
         'password' => '{password}'
     ],
-    'scope'   => ['project' => ['id' => '{projectId}']]
 ]);
 
 $service = $openstack->objectStoreV1();
-
 $account = $service->getAccount();
 
 $account->resetMetadata([

diff --git a/samples/ObjectStore/v1/containers/create.php b/samples/ObjectStore/v1/containers/create.php
@@ -7,13 +7,12 @@
     'region'  => '{region}',
     'user'    => [
         'id'       => '{userId}',
-        'password' => '{password}'
+        'password' => '{password}',
     ],
-    'scope'   => ['project' => ['id' => '{projectId}']]
 ]);
 
 $service = $openstack->objectStoreV1();
 
 $container = $service->createContainer([
-    'name' => '{containerName}'
+    'name' => '{containerName}',
 ]);
diff --git a/samples/ObjectStore/v1/containers/delete.php b/samples/ObjectStore/v1/containers/delete.php
@@ -7,11 +7,11 @@
     'region'  => '{region}',
     'user'    => [
         'id'       => '{userId}',
-        'password' => '{password}'
+        'password' => '{password}',
     ],
-    'scope'   => ['project' => ['id' => '{projectId}']]
 ]);
 
-$openstack->objectStoreV1()
-          ->getContainer('{containerName}')
-          ->delete();
+$service = $openstack->objectStoreV1();
+$container = $service->getContainer('{containerName}');
+
+$container->delete();
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		.. \|method\| replace::

		.. include:: /common/create-service.rst