mirror of
https://github.com/LukeHagar/discoursejs.git
synced 2025-12-06 12:27:48 +00:00
420 lines
22 KiB
Markdown
420 lines
22 KiB
Markdown
# Uploads
|
|
(*uploads*)
|
|
|
|
### Available Operations
|
|
|
|
* [abortMultipart](#abortmultipart) - Abort multipart upload
|
|
* [batchPresignMultipartParts](#batchpresignmultipartparts) - Generates batches of presigned URLs for multipart parts
|
|
* [completeExternalUpload](#completeexternalupload) - Completes a direct external upload
|
|
* [completeMultipart](#completemultipart) - Complete multipart upload
|
|
* [createMultipartUpload](#createmultipartupload) - Creates a multipart external upload
|
|
* [createUpload](#createupload) - Creates an upload
|
|
* [generatePresignedPut](#generatepresignedput) - Initiates a direct external upload
|
|
|
|
## abortMultipart
|
|
|
|
This endpoint aborts the multipart upload initiated with /create-multipart.
|
|
This should be used when cancelling the upload. It does not matter if parts
|
|
were already uploaded into the external storage provider.
|
|
|
|
You must have the correct permissions and CORS settings configured in your
|
|
external provider. We support AWS S3 as the default. See:
|
|
|
|
https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.
|
|
|
|
An external file store must be set up and `enable_direct_s3_uploads` must
|
|
be set to true for this endpoint to function.
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.abortMultipart({
|
|
externalUploadIdentifier: "84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ",
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
| `request` | [operations.AbortMultipartRequestBody](../../sdk/models/operations/abortmultipartrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.AbortMultipartResponse](../../sdk/models/operations/abortmultipartresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|
|
|
|
## batchPresignMultipartParts
|
|
|
|
Multipart uploads are uploaded in chunks or parts to individual presigned
|
|
URLs, similar to the one generated by /generate-presigned-put. The part
|
|
numbers provided must be between 1 and 10000. The total number of parts
|
|
will depend on the chunk size in bytes that you intend to use to upload
|
|
each chunk. For example a 12MB file may have 2 5MB chunks and a final
|
|
2MB chunk, for part numbers 1, 2, and 3.
|
|
|
|
This endpoint will return a presigned URL for each part number provided,
|
|
which you can then use to send PUT requests for the binary chunk corresponding
|
|
to that part. When the part is uploaded, the provider should return an
|
|
ETag for the part, and this should be stored along with the part number,
|
|
because this is needed to complete the multipart upload.
|
|
|
|
You must have the correct permissions and CORS settings configured in your
|
|
external provider. We support AWS S3 as the default. See:
|
|
|
|
https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.
|
|
|
|
An external file store must be set up and `enable_direct_s3_uploads` must
|
|
be set to true for this endpoint to function.
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.batchPresignMultipartParts({
|
|
partNumbers: [
|
|
1,
|
|
2,
|
|
3,
|
|
],
|
|
uniqueIdentifier: "66e86218-80d9-4bda-b4d5-2b6def968705",
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
|
|
| `request` | [operations.BatchPresignMultipartPartsRequestBody](../../sdk/models/operations/batchpresignmultipartpartsrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.BatchPresignMultipartPartsResponse](../../sdk/models/operations/batchpresignmultipartpartsresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|
|
|
|
## completeExternalUpload
|
|
|
|
Completes an external upload initialized with /get-presigned-put. The
|
|
file will be moved from its temporary location in external storage to
|
|
a final destination in the S3 bucket. An Upload record will also be
|
|
created in the database in most cases.
|
|
|
|
If a sha1-checksum was provided in the initial request it will also
|
|
be compared with the uploaded file in storage to make sure the same
|
|
file was uploaded. The file size will be compared for the same reason.
|
|
|
|
You must have the correct permissions and CORS settings configured in your
|
|
external provider. We support AWS S3 as the default. See:
|
|
|
|
https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.
|
|
|
|
An external file store must be set up and `enable_direct_s3_uploads` must
|
|
be set to true for this endpoint to function.
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.completeExternalUpload({
|
|
forPrivateMessage: "true",
|
|
forSiteSetting: "true",
|
|
pasted: "true",
|
|
uniqueIdentifier: "66e86218-80d9-4bda-b4d5-2b6def968705",
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
| `request` | [operations.CompleteExternalUploadRequestBody](../../sdk/models/operations/completeexternaluploadrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.CompleteExternalUploadResponse](../../sdk/models/operations/completeexternaluploadresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|
|
|
|
## completeMultipart
|
|
|
|
Completes the multipart upload in the external store, and copies the
|
|
file from its temporary location to its final location in the store.
|
|
All of the parts must have been uploaded to the external storage provider.
|
|
An Upload record will be completed in most cases once the file is copied
|
|
to its final location.
|
|
|
|
You must have the correct permissions and CORS settings configured in your
|
|
external provider. We support AWS S3 as the default. See:
|
|
|
|
https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.
|
|
|
|
An external file store must be set up and `enable_direct_s3_uploads` must
|
|
be set to true for this endpoint to function.
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.completeMultipart({
|
|
parts: [
|
|
"<value>",
|
|
"<value>",
|
|
],
|
|
uniqueIdentifier: "66e86218-80d9-4bda-b4d5-2b6def968705",
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
| `request` | [operations.CompleteMultipartRequestBody](../../sdk/models/operations/completemultipartrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.CompleteMultipartResponse](../../sdk/models/operations/completemultipartresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|
|
|
|
## createMultipartUpload
|
|
|
|
Creates a multipart upload in the external storage provider, storing
|
|
a temporary reference to the external upload similar to /get-presigned-put.
|
|
|
|
You must have the correct permissions and CORS settings configured in your
|
|
external provider. We support AWS S3 as the default. See:
|
|
|
|
https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.
|
|
|
|
An external file store must be set up and `enable_direct_s3_uploads` must
|
|
be set to true for this endpoint to function.
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
import { UploadType } from "@lukehagar/discoursejs/dist/sdk/models/operations";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.createMultipartUpload({
|
|
fileName: "IMG_2021.jpeg",
|
|
fileSize: 4096,
|
|
metadata: {},
|
|
uploadType: UploadType.CardBackground,
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
| `request` | [operations.CreateMultipartUploadRequestBody](../../sdk/models/operations/createmultipartuploadrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.CreateMultipartUploadResponse](../../sdk/models/operations/createmultipartuploadresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|
|
|
|
## createUpload
|
|
|
|
Creates an upload
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
import { TypeT } from "@lukehagar/discoursejs/dist/sdk/models/operations";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.createUpload({
|
|
file: {
|
|
content: new TextEncoder().encode("0x5d6beD2Fe2"),
|
|
fileName: "blanche_centro_white.jpe",
|
|
},
|
|
type: TypeT.CardBackground,
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
| `request` | [operations.CreateUploadRequestBody](../../sdk/models/operations/createuploadrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.CreateUploadResponse](../../sdk/models/operations/createuploadresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|
|
|
|
## generatePresignedPut
|
|
|
|
Direct external uploads bypass the usual method of creating uploads
|
|
via the POST /uploads route, and upload directly to an external provider,
|
|
which by default is S3. This route begins the process, and will return
|
|
a unique identifier for the external upload as well as a presigned URL
|
|
which is where the file binary blob should be uploaded to.
|
|
|
|
Once the upload is complete to the external service, you must call the
|
|
POST /complete-external-upload route using the unique identifier returned
|
|
by this route, which will create any required Upload record in the Discourse
|
|
database and also move file from its temporary location to the final
|
|
destination in the external storage service.
|
|
|
|
You must have the correct permissions and CORS settings configured in your
|
|
external provider. We support AWS S3 as the default. See:
|
|
|
|
https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.
|
|
|
|
An external file store must be set up and `enable_direct_s3_uploads` must
|
|
be set to true for this endpoint to function.
|
|
|
|
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import { SDK } from "@lukehagar/discoursejs";
|
|
import { GeneratePresignedPutType } from "@lukehagar/discoursejs/dist/sdk/models/operations";
|
|
|
|
async function run() {
|
|
const sdk = new SDK();
|
|
|
|
const res = await sdk.uploads.generatePresignedPut({
|
|
fileName: "IMG_2021.jpeg",
|
|
fileSize: 4096,
|
|
metadata: {},
|
|
type: GeneratePresignedPutType.CardBackground,
|
|
});
|
|
|
|
if (res.statusCode == 200) {
|
|
// handle response
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
| `request` | [operations.GeneratePresignedPutRequestBody](../../sdk/models/operations/generatepresignedputrequestbody.md) | :heavy_check_mark: | The request object to use for the request. |
|
|
| `config` | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign: | Available config options for making requests. |
|
|
|
|
|
|
### Response
|
|
|
|
**Promise<[operations.GeneratePresignedPutResponse](../../sdk/models/operations/generatepresignedputresponse.md)>**
|
|
### Errors
|
|
|
|
| Error Object | Status Code | Content Type |
|
|
| --------------- | --------------- | --------------- |
|
|
| errors.SDKError | 4xx-5xx | */* |
|