> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/documentation/en/framework/externals/cloud.md).

# Cloud Services and Callbacks

Integrate object storage, cloud communication and WeChat services, and correctly handle callback verification and repeated notifications.

The cloud adapter integrates the remote protocol framework, but the configuration, calling permissions and business completion conditions still need to be clearly defined by the application. Reading a storage object, sending notifications, and receiving payment callbacks cannot use the same retry or confirmation strategy.

## Capability and Configuration Portal

| Expand | Current main capabilities                                                | Configuration location                                 |
| ------ | ------------------------------------------------------------------------ | ------------------------------------------------------ |
| Amazon | S3 and compatible object storage                                         | `/Externals/Amazon/ConnectionSettings`                 |
| Aliyun | OSS, messaging, SMS/voice, mobile push                                   | Corresponding service settings for `/Externals/Aliyun` |
| Wechat | Accounts, public platforms, third-party platforms and payment adaptation | Included accounts, certificates and service options    |

Each main package and Web/API/Gateway are different deployment products. There is no need to deploy a callback gateway when you only need to access storage; when you need to receive callbacks, just installing the client main package will not automatically provide an HTTP entry.

## Object Storage Basics

Object storage locates data by Bucket and Key, and directories are usually just key prefixes. The framework file system provides a unified path, but behaviors such as renaming, appending, enumerating, and random writing may not be the same as local disks.

Amazon plugin registration `zfs.s3`, the basePath of Discussions.option is zfs.s3:/zongsoft-discussions/, where zongsoft-discussions is the Bucket configured by this module. Aliyun OSS uses `zfs.oss`. Bucket selection and Key prefix should be subject to business permissions, and do not use the full path provided by the user directly for cross-tenant access.

The long text of Discussions is saved as an external file by ContentType and written by Utility.WriteTextFile via the unified file system. path is generated by module path rules, not any external input; this method will create or overwrite the target, and the application must prepare its own test Bucket and credentials before running.

Source: [src/Utility.cs](https://github.com/Zongsoft/Zongsoft.Discussions/blob/main/src/Utility.cs#L241) (excerpt; see source for context).

{% code title="Utility.cs" %}

```csharp
public static bool WriteTextFile(string path, string content)
{
	if(string.IsNullOrWhiteSpace(path))
		throw new ArgumentNullException(nameof(path));

	if(string.IsNullOrWhiteSpace(content))
		return false;

	using(var stream = FileSystem.File.Open(path, FileMode.Create, FileAccess.Write))
	{
		using(var writer = new StreamWriter(stream, System.Text.Encoding.UTF8))
		{
			writer.Write(content);
		}
	}

	return true;
}
```

{% endcode %}

The Amazon connection driver is `amazon.s3`, which supports region, endpoint, and credential configuration; custom endpoints will use path addressing. Whether the service account has the required operation permissions should be verified on dedicated resources. The using above ensures that the writer and stream are released. The module's MutateContentAsync cleans up new files when database writing fails, see [Transactions and Consistency](/documentation/en/framework/data/transactions.md) for details; such file operations are still synchronous calls. Just because the outer data service is an asynchronous method does not mean that all underlying storage operations are non-blocking.

## Aliyun Service Configuration

`general` Select the service center and internal and external network, and the named certificate saves the access credentials; Bucket, message, communication template and push application can select the corresponding services and credentials according to the configuration. The Certificate here is the credential model of the adapter and should not be understood as a TLS certificate file.

SMS and voice operations refer to the template configured in the cloud, and the parameters must comply with the template definition; the push must also be applied correctly and the target type is correct. A successful call usually means that the platform accepts the request, and delivery or business completion may be confirmed through subsequent queries, receipts, or callbacks. Avoid blindly applying universal retries to send operations.

## Different Identities in WeChat

Application identification, user identification under the application, third-party platform tokens and payment merchant identities belong to different scopes. Applications cannot use identifiers from one scope directly to another scope, nor can they treat user authorization as merchant payment permissions.

The third-party platform process usually includes receiving platform tickets, obtaining platform access tokens, generating pre-authorization information, users completing authorization, saving and refreshing the authorizer credentials. The specific fields and duration are subject to the corresponding platform interface and current adapter implementation. The duration in the old README is not written as an immutable protocol.

## The Callback Gateway Is Not an Automatic Signature Verifier

Currently both gateways expose the following dispatch entries:

| gateway | Default POST route                         |
| ------- | ------------------------------------------ |
| Aliyun  | `/Externals/Aliyun/Fallback/{name}/{key?}` |
| Wechat  | `/Externals/Wechat/Fallback/{name}/{key?}` |

`name` is the handler dispatch key, not the source authentication. The handler should verify the original data according to the specific service agreement, check the validity, and decrypt it if necessary before entering the business processing. WeChat Gateway also does not automatically provide the GET address verification required by all products.

Wechat can register the constructed handler with `FallbackExecutor.Instance.Handlers` during the startup phase; Aliyun's current plugin node is bound to the executor itself, and its `Handlers` attribute needs to be exposed before appending the collection. The complete registration fragments can be found at [WeChat gateway](https://github.com/Zongsoft/framework/blob/main/externals/wechat/gateway/README.zh-Hans.md) and [Alibaba Cloud Gateway](https://github.com/Zongsoft/framework/blob/main/externals/aliyun/gateway/README.zh-Hans.md) respectively.

## Callback Responses and Idempotent

The gateway hands over the request flow and parameters to the handler. The stream is only valid within the request lifecycle; when background processing is required, the necessary content should be copied and reliably saved within the size limit. The content returned by handler for non-empty results. The empty result is usually `204`. This may not meet the confirmation format required by the server and must be verified according to the target protocol.

{% hint style="warning" %}
🚨 The gateway will not automatically complete signature verification, decryption and replay protection for all products. Callbacks may be repeated, and business updates should be deduplicated by verified event or transaction identifiers; receiving correct signatures does not mean that the same side effect can be executed multiple times.
{% endhint %}

First use desensitized fixed requests to verify signatures, error signatures, duplicates, expiration and processing failures, and then integrate the dedicated platform test environment. Logging requests associate identification and error types to avoid saving access keys, full signatures, certificate secrets, or raw transaction data.

Source references: [Amazon](https://github.com/Zongsoft/framework/tree/main/externals/amazon), [Aliyun](https://github.com/Zongsoft/framework/tree/main/externals/aliyun), [Wechat](https://github.com/Zongsoft/framework/tree/main/externals/wechat).

## Continue Reading by Project

[Aliyun](/documentation/en/framework/externals/projects/aliyun.md) · [Amazon](/documentation/en/framework/externals/projects/amazon.md) · [Wechat](/documentation/en/framework/externals/projects/wechat.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zongsoft.com/documentation/en/framework/externals/cloud.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.