feat(client-storage-gateway): This release adds support to invoke a process that cleans the specified file share's cache of file entries that are failing upload to Amazon S3.

awstools · awstools · commit 6ee1cf4d6fe4 · 2025-02-27T19:20:42.000Z
diff --git a/clients/client-storage-gateway/README.md b/clients/client-storage-gateway/README.md
@@ -706,6 +706,14 @@ DisassociateFileSystem
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/storage-gateway/command/DisassociateFileSystemCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-storage-gateway/Interface/DisassociateFileSystemCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-storage-gateway/Interface/DisassociateFileSystemCommandOutput/)
 
+</details>
+<details>
+<summary>
+EvictFilesFailingUpload
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/storage-gateway/command/EvictFilesFailingUploadCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-storage-gateway/Interface/EvictFilesFailingUploadCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-storage-gateway/Interface/EvictFilesFailingUploadCommandOutput/)
+
 </details>
 <details>
 <summary>
diff --git a/clients/client-storage-gateway/src/StorageGateway.ts b/clients/client-storage-gateway/src/StorageGateway.ts
@@ -265,6 +265,11 @@ import {
   DisassociateFileSystemCommandInput,
   DisassociateFileSystemCommandOutput,
 } from "./commands/DisassociateFileSystemCommand";
+import {
+  EvictFilesFailingUploadCommand,
+  EvictFilesFailingUploadCommandInput,
+  EvictFilesFailingUploadCommandOutput,
+} from "./commands/EvictFilesFailingUploadCommand";
 import { JoinDomainCommand, JoinDomainCommandInput, JoinDomainCommandOutput } from "./commands/JoinDomainCommand";
 import {
   ListAutomaticTapeCreationPoliciesCommand,
@@ -507,6 +512,7 @@ const commands = {
   DetachVolumeCommand,
   DisableGatewayCommand,
   DisassociateFileSystemCommand,
+  EvictFilesFailingUploadCommand,
   JoinDomainCommand,
   ListAutomaticTapeCreationPoliciesCommand,
   ListCacheReportsCommand,
@@ -1402,6 +1408,23 @@ export interface StorageGateway {
     cb: (err: any, data?: DisassociateFileSystemCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link EvictFilesFailingUploadCommand}
+   */
+  evictFilesFailingUpload(
+    args: EvictFilesFailingUploadCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<EvictFilesFailingUploadCommandOutput>;
+  evictFilesFailingUpload(
+    args: EvictFilesFailingUploadCommandInput,
+    cb: (err: any, data?: EvictFilesFailingUploadCommandOutput) => void
+  ): void;
+  evictFilesFailingUpload(
+    args: EvictFilesFailingUploadCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: EvictFilesFailingUploadCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link JoinDomainCommand}
    */
diff --git a/clients/client-storage-gateway/src/StorageGatewayClient.ts b/clients/client-storage-gateway/src/StorageGatewayClient.ts
@@ -192,6 +192,10 @@ import {
   DisassociateFileSystemCommandInput,
   DisassociateFileSystemCommandOutput,
 } from "./commands/DisassociateFileSystemCommand";
+import {
+  EvictFilesFailingUploadCommandInput,
+  EvictFilesFailingUploadCommandOutput,
+} from "./commands/EvictFilesFailingUploadCommand";
 import { JoinDomainCommandInput, JoinDomainCommandOutput } from "./commands/JoinDomainCommand";
 import {
   ListAutomaticTapeCreationPoliciesCommandInput,
@@ -374,6 +378,7 @@ export type ServiceInputTypes =
   | DetachVolumeCommandInput
   | DisableGatewayCommandInput
   | DisassociateFileSystemCommandInput
+  | EvictFilesFailingUploadCommandInput
   | JoinDomainCommandInput
   | ListAutomaticTapeCreationPoliciesCommandInput
   | ListCacheReportsCommandInput
@@ -474,6 +479,7 @@ export type ServiceOutputTypes =
   | DetachVolumeCommandOutput
   | DisableGatewayCommandOutput
   | DisassociateFileSystemCommandOutput
+  | EvictFilesFailingUploadCommandOutput
   | JoinDomainCommandOutput
   | ListAutomaticTapeCreationPoliciesCommandOutput
   | ListCacheReportsCommandOutput
diff --git a/clients/client-storage-gateway/src/commands/EvictFilesFailingUploadCommand.ts b/clients/client-storage-gateway/src/commands/EvictFilesFailingUploadCommand.ts
@@ -0,0 +1,113 @@
+// smithy-typescript generated code
+import { getEndpointPlugin } from "@smithy/middleware-endpoint";
+import { getSerdePlugin } from "@smithy/middleware-serde";
+import { Command as $Command } from "@smithy/smithy-client";
+import { MetadataBearer as __MetadataBearer } from "@smithy/types";
+
+import { commonParams } from "../endpoint/EndpointParameters";
+import { EvictFilesFailingUploadInput, EvictFilesFailingUploadOutput } from "../models/models_0";
+import { de_EvictFilesFailingUploadCommand, se_EvictFilesFailingUploadCommand } from "../protocols/Aws_json1_1";
+import { ServiceInputTypes, ServiceOutputTypes, StorageGatewayClientResolvedConfig } from "../StorageGatewayClient";
+
+/**
+ * @public
+ */
+export type { __MetadataBearer };
+export { $Command };
+/**
+ * @public
+ *
+ * The input for {@link EvictFilesFailingUploadCommand}.
+ */
+export interface EvictFilesFailingUploadCommandInput extends EvictFilesFailingUploadInput {}
+/**
+ * @public
+ *
+ * The output of {@link EvictFilesFailingUploadCommand}.
+ */
+export interface EvictFilesFailingUploadCommandOutput extends EvictFilesFailingUploadOutput, __MetadataBearer {}
+
+/**
+ * <p>Starts a process that cleans the specified file share's cache of file entries that are
+ *          failing upload to Amazon S3. This API operation reports success if the request is
+ *          received with valid arguments, and there are no other cache clean operations currently
+ *          in-progress for the specified file share. After a successful request, the cache clean
+ *          operation occurs asynchronously and reports progress using CloudWatch logs and
+ *          notifications.</p>
+ *          <important>
+ *             <p>If <code>ForceRemove</code> is set to <code>True</code>, the cache clean operation
+ *             will delete file data from the gateway which might otherwise be recoverable. We
+ *             recommend using this operation only after all other methods to clear files failing
+ *             upload have been exhausted, and if your business need outweighs the potential data
+ *             loss.</p>
+ *          </important>
+ * @example
+ * Use a bare-bones client and the command you need to make an API call.
+ * ```javascript
+ * import { StorageGatewayClient, EvictFilesFailingUploadCommand } from "@aws-sdk/client-storage-gateway"; // ES Modules import
+ * // const { StorageGatewayClient, EvictFilesFailingUploadCommand } = require("@aws-sdk/client-storage-gateway"); // CommonJS import
+ * const client = new StorageGatewayClient(config);
+ * const input = { // EvictFilesFailingUploadInput
+ *   FileShareARN: "STRING_VALUE", // required
+ *   ForceRemove: true || false,
+ * };
+ * const command = new EvictFilesFailingUploadCommand(input);
+ * const response = await client.send(command);
+ * // { // EvictFilesFailingUploadOutput
+ * //   NotificationId: "STRING_VALUE",
+ * // };
+ *
+ * ```
+ *
+ * @param EvictFilesFailingUploadCommandInput - {@link EvictFilesFailingUploadCommandInput}
+ * @returns {@link EvictFilesFailingUploadCommandOutput}
+ * @see {@link EvictFilesFailingUploadCommandInput} for command's `input` shape.
+ * @see {@link EvictFilesFailingUploadCommandOutput} for command's `response` shape.
+ * @see {@link StorageGatewayClientResolvedConfig | config} for StorageGatewayClient's `config` shape.
+ *
+ * @throws {@link InternalServerError} (server fault)
+ *  <p>An internal server error has occurred during the request. For more information, see the
+ *          error and message fields.</p>
+ *
+ * @throws {@link InvalidGatewayRequestException} (client fault)
+ *  <p>An exception occurred because an invalid gateway request was issued to the service. For
+ *          more information, see the error and message fields.</p>
+ *
+ * @throws {@link StorageGatewayServiceException}
+ * <p>Base exception class for all service exceptions from StorageGateway service.</p>
+ *
+ * @public
+ */
+export class EvictFilesFailingUploadCommand extends $Command
+  .classBuilder<
+    EvictFilesFailingUploadCommandInput,
+    EvictFilesFailingUploadCommandOutput,
+    StorageGatewayClientResolvedConfig,
+    ServiceInputTypes,
+    ServiceOutputTypes
+  >()
+  .ep(commonParams)
+  .m(function (this: any, Command: any, cs: any, config: StorageGatewayClientResolvedConfig, o: any) {
+    return [
+      getSerdePlugin(config, this.serialize, this.deserialize),
+      getEndpointPlugin(config, Command.getEndpointParameterInstructions()),
+    ];
+  })
+  .s("StorageGateway_20130630", "EvictFilesFailingUpload", {})
+  .n("StorageGatewayClient", "EvictFilesFailingUploadCommand")
+  .f(void 0, void 0)
+  .ser(se_EvictFilesFailingUploadCommand)
+  .de(de_EvictFilesFailingUploadCommand)
+  .build() {
+  /** @internal type navigation helper, not in runtime. */
+  protected declare static __types: {
+    api: {
+      input: EvictFilesFailingUploadInput;
+      output: EvictFilesFailingUploadOutput;
+    };
+    sdk: {
+      input: EvictFilesFailingUploadCommandInput;
+      output: EvictFilesFailingUploadCommandOutput;
+    };
+  };
+}
diff --git a/clients/client-storage-gateway/src/commands/index.ts b/clients/client-storage-gateway/src/commands/index.ts
@@ -54,6 +54,7 @@ export * from "./DescribeWorkingStorageCommand";
 export * from "./DetachVolumeCommand";
 export * from "./DisableGatewayCommand";
 export * from "./DisassociateFileSystemCommand";
+export * from "./EvictFilesFailingUploadCommand";
 export * from "./JoinDomainCommand";
 export * from "./ListAutomaticTapeCreationPoliciesCommand";
 export * from "./ListCacheReportsCommand";
diff --git a/clients/client-storage-gateway/src/models/models_0.ts b/clients/client-storage-gateway/src/models/models_0.ts
@@ -5759,6 +5759,57 @@ export interface Disk {
   DiskAttributeList?: string[] | undefined;
 }
 
+/**
+ * @public
+ */
+export interface EvictFilesFailingUploadInput {
+  /**
+   * <p>The Amazon Resource Name (ARN) of the file share for which you want to start the cache
+   *          clean operation.</p>
+   * @public
+   */
+  FileShareARN: string | undefined;
+
+  /**
+   * <p>Specifies whether cache entries with full or partial file data currently stored on the
+   *          gateway will be forcibly removed by the cache clean operation.</p>
+   *          <p>Valid arguments:</p>
+   *          <ul>
+   *             <li>
+   *                <p>
+   *                   <code>False</code> - The cache clean operation skips cache entries failing upload
+   *                if they are associated with data currently stored on the gateway. This preserves the
+   *                cached data.</p>
+   *             </li>
+   *             <li>
+   *                <p>
+   *                   <code>True</code> - The cache clean operation removes cache entries failing upload
+   *                even if they are associated with data currently stored on the gateway. This deletes
+   *                the cached data.</p>
+   *                <important>
+   *                   <p>If <code>ForceRemove</code> is set to <code>True</code>, the cache clean
+   *                   operation will delete file data from the gateway which might otherwise be
+   *                   recoverable.</p>
+   *                </important>
+   *             </li>
+   *          </ul>
+   * @public
+   */
+  ForceRemove?: boolean | undefined;
+}
+
+/**
+ * @public
+ */
+export interface EvictFilesFailingUploadOutput {
+  /**
+   * <p>The randomly generated ID of the CloudWatch notification associated with the
+   *          cache clean operation. This ID is in UUID format.</p>
+   * @public
+   */
+  NotificationId?: string | undefined;
+}
+
 /**
  * @public
  * @enum
diff --git a/clients/client-storage-gateway/src/protocols/Aws_json1_1.ts b/clients/client-storage-gateway/src/protocols/Aws_json1_1.ts
@@ -162,6 +162,10 @@ import {
   DisassociateFileSystemCommandInput,
   DisassociateFileSystemCommandOutput,
 } from "../commands/DisassociateFileSystemCommand";
+import {
+  EvictFilesFailingUploadCommandInput,
+  EvictFilesFailingUploadCommandOutput,
+} from "../commands/EvictFilesFailingUploadCommand";
 import { JoinDomainCommandInput, JoinDomainCommandOutput } from "../commands/JoinDomainCommand";
 import {
   ListAutomaticTapeCreationPoliciesCommandInput,
@@ -345,6 +349,7 @@ import {
   DisableGatewayInput,
   DisassociateFileSystemInput,
   EndpointNetworkConfiguration,
+  EvictFilesFailingUploadInput,
   InternalServerError,
   InvalidGatewayRequestException,
   JoinDomainInput,
@@ -1117,6 +1122,19 @@ export const se_DisassociateFileSystemCommand = async (
   return buildHttpRpcRequest(context, headers, "/", undefined, body);
 };
 
+/**
+ * serializeAws_json1_1EvictFilesFailingUploadCommand
+ */
+export const se_EvictFilesFailingUploadCommand = async (
+  input: EvictFilesFailingUploadCommandInput,
+  context: __SerdeContext
+): Promise<__HttpRequest> => {
+  const headers: __HeaderBag = sharedHeaders("EvictFilesFailingUpload");
+  let body: any;
+  body = JSON.stringify(_json(input));
+  return buildHttpRpcRequest(context, headers, "/", undefined, body);
+};
+
 /**
  * serializeAws_json1_1JoinDomainCommand
  */
@@ -2737,6 +2755,26 @@ export const de_DisassociateFileSystemCommand = async (
   return response;
 };
 
+/**
+ * deserializeAws_json1_1EvictFilesFailingUploadCommand
+ */
+export const de_EvictFilesFailingUploadCommand = async (
+  output: __HttpResponse,
+  context: __SerdeContext
+): Promise<EvictFilesFailingUploadCommandOutput> => {
+  if (output.statusCode >= 300) {
+    return de_CommandError(output, context);
+  }
+  const data: any = await parseBody(output.body, context);
+  let contents: any = {};
+  contents = _json(data);
+  const response: EvictFilesFailingUploadCommandOutput = {
+    $metadata: deserializeMetadata(output),
+    ...contents,
+  };
+  return response;
+};
+
 /**
  * deserializeAws_json1_1JoinDomainCommand
  */
@@ -3743,6 +3781,8 @@ const de_ServiceUnavailableErrorRes = async (
 
 // se_EndpointNetworkConfiguration omitted.
 
+// se_EvictFilesFailingUploadInput omitted.
+
 // se_FileShareARNList omitted.
 
 // se_FileShareClientList omitted.
@@ -4152,6 +4192,8 @@ const de_DescribeTapesOutput = (output: any, context: __SerdeContext): DescribeT
 
 // de_errorDetails omitted.
 
+// de_EvictFilesFailingUploadOutput omitted.
+
 // de_FileShareClientList omitted.
 
 // de_FileShareInfo omitted.
diff --git a/codegen/sdk-codegen/aws-models/storage-gateway.json b/codegen/sdk-codegen/aws-models/storage-gateway.json
