diff --git a/core/src/services/oss/backend.rs b/core/src/services/oss/backend.rs index b4860fc9961..81fb1613745 100644 --- a/core/src/services/oss/backend.rs +++ b/core/src/services/oss/backend.rs @@ -40,78 +40,7 @@ use crate::*; const DEFAULT_WRITE_MIN_SIZE: usize = 8 * 1024 * 1024; /// Aliyun Object Storage Service (OSS) support -/// -/// # Capabilities -/// -/// This service can be used to: -/// -/// - [x] stat -/// - [x] read -/// - [x] write -/// - [x] append -/// - [x] create_dir -/// - [x] delete -/// - [x] copy -/// - [ ] rename -/// - [x] list -/// - [x] scan -/// - [x] presign -/// - [ ] blocking -/// -/// # Configuration -/// -/// - `root`: Set the work dir for backend. -/// - `bucket`: Set the container name for backend. -/// - `endpoint`: Set the endpoint for backend. -/// - `presign_endpoint`: Set the endpoint for presign. -/// - `access_key_id`: Set the access_key_id for backend. -/// - `access_key_secret`: Set the access_key_secret for backend. -/// - `role_arn`: Set the role of backend. -/// - `oidc_token`: Set the oidc_token for backend. -/// - `allow_anonymous`: Set the backend access OSS in anonymous way. -/// -/// Refer to [`OssBuilder`]'s public API docs for more information. -/// -/// # Example -/// -/// ## Via Builder -/// -/// ```no_run -/// use std::sync::Arc; -/// -/// use anyhow::Result; -/// use opendal::services::Oss; -/// use opendal::Operator; -/// -/// #[tokio::main] -/// async fn main() -> Result<()> { -/// // Create OSS backend builder. -/// let mut builder = Oss::default(); -/// // Set the root for oss, all operations will happen under this root. -/// // -/// // NOTE: the root must be absolute path. -/// builder.root("/path/to/dir"); -/// // Set the bucket name, this is required. -/// builder.bucket("test"); -/// // Set the endpoint. -/// // -/// // For example: -/// // - "https://oss-ap-northeast-1.aliyuncs.com" -/// // - "https://oss-hangzhou.aliyuncs.com" -/// builder.endpoint("https://oss-cn-beijing.aliyuncs.com"); -/// // Set the access_key_id and access_key_secret. -/// // -/// // OpenDAL will try load credential from the env. -/// // If credential not set and no valid credential in env, OpenDAL will -/// // send request without signing like anonymous user. -/// builder.access_key_id("access_key_id"); -/// builder.access_key_secret("access_key_secret"); -/// -/// let op: Operator = Operator::new(builder)?.finish(); -/// -/// Ok(()) -/// } -/// ``` +#[doc = include_str!("docs.md")] #[derive(Default)] pub struct OssBuilder { root: Option, diff --git a/core/src/services/oss/docs.md b/core/src/services/oss/docs.md new file mode 100644 index 00000000000..131afaa3f7b --- /dev/null +++ b/core/src/services/oss/docs.md @@ -0,0 +1,73 @@ + + +# Capabilities + +This service can be used to: + +- [x] stat +- [x] read +- [x] write +- [x] append +- [x] create_dir +- [x] delete +- [x] copy +- [ ] rename +- [x] list +- [x] scan +- [x] presign +- [ ] blocking + +# Configuration + +- `root`: Set the work dir for backend. +- `bucket`: Set the container name for backend. +- `endpoint`: Set the endpoint for backend. +- `presign_endpoint`: Set the endpoint for presign. +- `access_key_id`: Set the access_key_id for backend. +- `access_key_secret`: Set the access_key_secret for backend. +- `role_arn`: Set the role of backend. +- `oidc_token`: Set the oidc_token for backend. +- `allow_anonymous`: Set the backend access OSS in anonymous way. + +Refer to [`OssBuilder`]'s public API docs for more information. + +# Example + +## Via Builder + +```rust +use std::sync::Arc; + +use anyhow::Result; +use opendal::services::Oss; +use opendal::Operator; + +#[tokio::main] +async fn main() -> Result<()> { + // Create OSS backend builder. + let mut builder = Oss::default(); + // Set the root for oss, all operations will happen under this root. + // + // NOTE: the root must be absolute path. + builder.root("/path/to/dir"); + // Set the bucket name, this is required. + builder.bucket("test"); + // Set the endpoint. + // + // For example: + // - "https://oss-ap-northeast-1.aliyuncs.com" + // - "https://oss-hangzhou.aliyuncs.com" + builder.endpoint("https://oss-cn-beijing.aliyuncs.com"); + // Set the access_key_id and access_key_secret. + // + // OpenDAL will try load credential from the env. + // If credential not set and no valid credential in env, OpenDAL will + // send request without signing like anonymous user. + builder.access_key_id("access_key_id"); + builder.access_key_secret("access_key_secret"); + + let op: Operator = Operator::new(builder)?.finish(); + + Ok(()) +} +``` \ No newline at end of file diff --git a/website/docs/services/oss.mdx b/website/docs/services/oss.mdx new file mode 100644 index 00000000000..28e40daee83 --- /dev/null +++ b/website/docs/services/oss.mdx @@ -0,0 +1,75 @@ +--- +title: OSS +--- + +Aliyun Object Storage Service (OSS) support. + +import Docs from '../../../core/src/services/oss/docs.md' + + + + +### Via Config + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```rust +use std::sync::Arc; + +use anyhow::Result; +use opendal::Scheme; +use opendal::Operator; + +#[tokio::main] +async fn main() -> Result<()> { + let mut map = HashMap::new(); + map.insert("root".to_string(), "/path/to/dir".to_string()); + map.insert("bucket".to_string(), "test".to_string()); + map.insert("endpoint".to_string(), "https://oss-cn-beijing.aliyuncs.com".to_string()); + map.insert("access_key_id".to_string(), "access_key_id".to_string()); + map.insert("access_key_secret".to_string(), "access_key_secret".to_string()); + + let op: Operator = Operator::via_map(Scheme::Oss, map)?; + Ok(()) +} +``` + + + + +```javascript +import { Operator } from "opendal"; + +async function main() { + const op = new Operator("oss", { + root: "/path/to/dir", + bucket: "test", + endpoint: "https://oss-cn-beijing.aliyuncs.com", + access_key_id: "access_key_id", + access_key_secret: "access_key_secret", + }); +} +``` + + + + +```python +import opendal + +op = opendal.Operator("oss", + root:"/path/to/dir", + bucket="test", + endpoint="https://oss-cn-beijing.aliyuncs.com", + access_key_id="access_key_id", + access_key_secret="access_key_secret", +) +``` + + + +