TrueCloudLab/frostfs-http-gw
14
0
Fork 16
Code Issues 6 Pull requests 3 Projects Releases 7 Activity Actions

Readme edits

Browse source 
Add new info, new sections, examples

Signed-off-by: Angira Kekteeva <kira@nspcc.ru>
This commit is contained in:
Angira Kekteeva 2021-05-17 17:30:16 +03:00 committed by Roman Khimov
parent 685c229a97
commit ebb97a215d
1 changed files with 66 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
README.md
View file

@ -47,6 +47,10 @@ can be done either via `-p` parameter or via `HTTP_GW_PEERS_<N>_ADDRESS` and
`HTTP_GW_PEERS_<N>_WEIGHT` environment variables (the gate supports multiple `HTTP_GW_PEERS_<N>_WEIGHT` environment variables (the gate supports multiple
NeoFS nodes with weighted load balancing). NeoFS nodes with weighted load balancing).
If you're launching HTTP gateway in bundle with [neofs-dev-env](https://github.com/nspcc-dev/neofs-dev-env),
you can get an IP address of the node in output of `make hosts` command
(with s0*.neofs.devenv name).
These two commands are functionally equivalent, they run the gate with one These two commands are functionally equivalent, they run the gate with one
backend node (and otherwise default settings): backend node (and otherwise default settings):
``` ```
@ -82,8 +86,12 @@ This command will make gateway use 192.168.130.72 for 90% of requests and
By default gateway autogenerates key pair it will use for NeoFS requests. If By default gateway autogenerates key pair it will use for NeoFS requests. If
for some reason you need to have static keys you can pass them via `--key` for some reason you need to have static keys you can pass them via `--key`
parameter. The key can be a path to private key file (as raw bytes), a hex (or `-k`) parameter. The key can be a path to private key file (as raw bytes),
string or (unencrypted) WIF string. Example: a hex string or (unencrypted) WIF string:
```
$ neofs-http-gw -p $NEOFS_NODE -k $KEY
```
For example:
``` ```
$ neofs-http-gw -p 192.168.130.72:8080 -k KxDgvEKzgSBPPfuVfw67oPQBSjidEiqTHURKSDL1R7yGaGYAeYnr $ neofs-http-gw -p 192.168.130.72:8080 -k KxDgvEKzgSBPPfuVfw67oPQBSjidEiqTHURKSDL1R7yGaGYAeYnr
@ -171,26 +179,76 @@ and upload objects with it, but deleting, searching, managing ACLs, creating
containers and other activities are not supported and not planned to be containers and other activities are not supported and not planned to be
supported. supported.
### Preparation
Before uploading or downloading a file make sure you have a prepared container.
You can create it with instructions below.
Also in case of downloading you need to have a file inside a container.
#### Create a container
You can create a container via [neofs-cli](https://github.com/nspcc-dev/neofs-node/releases):
```
$ neofs-cli -r $NEOFS_NODE -k $KEY container create --policy $POLICY --basic-acl $ACL
```
where `$KEY` can be a path to private key file (as raw bytes), a hex string or
(unencrypted) WIF string,
`$ACL` -- hex encoded basic ACL value or keywords 'private, 'public', 'readonly' and
`$POLICY` -- QL-encoded or JSON-encoded placement policy or path to file with it
For example:
```
$ neofs-cli -r 192.168.130.72:8080 -k 6PYLKJhiSub5imt6WCVy6Quxtd9xu176omev1vWYovzkAQCTSQabAAQXii container create --policy "REP 3" --basic-acl public --await
```
If you launched nodes via [neofs-dev-env](https://github.com/nspcc-dev/neofs-dev-env)
you can get the key value from `wallets/wallet.json` or write the path to
the file `wallets/wallet.key`.
#### Prepare a file in a container
To create a file via [neofs-cli](https://github.com/nspcc-dev/neofs-node/releases), run a command below:
```
$ neofs-cli -r $NEOFS_NODE -k $KEY object put --file $FILENAME --cid $CID
```
where
`$KEY` -- the key, please read the information [above](#create-a-container),
`$CID` -- container ID.
For example:
```
$ neofs-cli -r 192.168.130.72:8080 -k 6PYLKJhiSub5imt6WCVy6Quxtd9xu176omev1vWYovzkAQCTSQabAAQXii object put --file cat.png --cid DPL2tpRiuDNmoTj5KZjD1nzDuCS8tVcxa7hsvSLDWpVM --attributes img_type=cat,my_attr=cute
```
### Downloading ### Downloading
#### Requests #### Requests
Basic downloading involves container and object ID and is done via GET ##### By IDs
requests to `/get/$CID/$OID` path, like this:
Basic downloading involves container ID and object ID and is done via GET
requests to `/get/$CID/$OID` path, where `$CID` is a container ID,
`$OID` is an object's (i.e. your file's) ID.
For example:
``` ```
$ wget http://localhost:8082/get/Dxhf4PNprrJHWWTG5RGLdfLkJiSQ3AQqit1MSnEPRkDZ/2m8PtaoricLouCn5zE8hAFr3gZEBDCZFe9BEgVJTSocY $ wget http://localhost:8082/get/Dxhf4PNprrJHWWTG5RGLdfLkJiSQ3AQqit1MSnEPRkDZ/2m8PtaoricLouCn5zE8hAFr3gZEBDCZFe9BEgVJTSocY
``` ```
##### By attributes
There is also more complex interface provided for attribute-based downloads, There is also more complex interface provided for attribute-based downloads,
it's usually used to retrieve files by their names, but any other attribute it's usually used to retrieve files by their names, but any other attribute
can be used as well. The generic syntax for it looks like this: can be used as well. The generic syntax for it looks like this:
```/get_by_attribute/$CID/$ATTRIBUTE_NAME/$ATTRIBUTE_VALUE``` ```/get_by_attribute/$CID/$ATTRIBUTE_NAME/$ATTRIBUTE_VALUE```
where `$CID` is a container ID, `$ATTRIBUTE_NAME` is the name of the attribute where
we want to use and `ATTRIBUTE_VALUE` is the value of this attribute that the `$CID` is a container ID,
target object should have. `$ATTRIBUTE_NAME` is the name of the attribute we want to use,
`$ATTRIBUTE_VALUE` is the value of this attribute that the target object should have.
If multiple objects have specified attribute with specified value, then the If multiple objects have specified attribute with specified value, then the
first one of them is returned (and you can't get others via this interface). first one of them is returned (and you can't get others via this interface).