Merge pull request #279103 from MicrosoftDocs/repo_sync_working_branch

Confirm merge from repo_sync_working_branch to main to sync with https://github.com/MicrosoftDocs/azure-docs (branch main)

Author: Taojunshen

articles/azure-fluid-relay/how-tos/container-recovery.md

@@ -12,55 +12,69 @@ In this scenario, we explore data recovery. We consider data to be corrupted whe
 
 ## How Fluid Framework and Azure Fluid Relay save state
 
-Fluid framework periodically saves state, called summary, without any explicit backup action initiated by the user. This workflow occurs every one (1) minute if there's no user activity, or sooner if there are more than 1000 pending ops present. Each pending op roughly translates to an individual user action (select, text input etc.) that wasn't summarized yet.
+Fluid Framework periodically saves snapshots of the data in the container, which summarize all changes made to the data up to that point.  During normal loading the latest snapshot is retrieved, and any subsequent changes are applied on top of that state.
+
+If the latest snapshot or subsequent changes are corrupt, Fluid may not be able to load them normally.  In this case, Fluid offers a collection of APIs to view the stored snapshot versions and load them in a view-only mode with no subsequent changes applied.  This allows the data to be extracted and optionally injected into a new container to resume collaboration.
 
 ## Azure client APIs
 
-We added the following methods to AzureClient that enable developers to recover data from corrupted containers. 
+### APIs for viewing and loading container versions
 
-`getContainerVersions(ID, options)`
+The AzureClient has the following methods to support this scenario:
 
-`getContainerVersions` allows developers to view the previously generated versions of the container.
+#### Get container versions
 
-`copyContainer(ID, containerSchema)`
+`getContainerVersions(id, options?)`
 
-`copyContainer` allows developers to generate a new detached container from a specific version of another container.
+Retrieve a list of available versions that may be loaded from.
 
-## Example recovery flow
+`Parameters:`
 
-```typescript
+*   `id`:  The container ID.  This is the same ID used when calling `getContainer`.
+*   `options?`:  Optionally, an options object to specify:
+    *   `maxCount`:  The maximum number of versions to retrieve.  If there are more versions available than requested, the newest versions will be retrieved.  **Default: 5**
+
+`Returns:` A promise which resolves to an array of objects that represent available versions (sorted newest to oldest). The objects have the following properties:
+
+*   `id`:  The version ID.
+    *   *Note*:  This is different from the container ID, and specifically references a snapshot version rather than the container.
+*   `date`:  The timestamp when the version was generated.
+
+#### View container version
+
+`viewContainerVersion(id, containerSchema, version, compatibilityMode)`
+
+Load a specific version of a container for viewing only.  Any version retrieved from `getContainerVersions` may be used, but for the purpose of recovering corrupted data it is recommended to start with the most-recent version and work backwards to find the most-recent uncorrupted version.
 
-async function recoverDoc(
-    client: AzureClient,
-    orgContainerId: string,
-    containerScema: ContainerSchema,
-): Promise<string> {
-    /* Collect doc versions */
-    let versions: AzureContainerVersion[] = [];
-    try {
-        versions = await client.getContainerVersions(orgContainerId);
-    } catch (e) {
-        return Promise.reject(new Error("Unable to get container versions."));
-    }
-
-    for (const version of versions) {
-        /* Versions are returned in chronological order.
-        Attempt to copy doc from next available version */
-        try {
-            const { container: newContainer } = await client.copyContainer(
-                orgContainerId,
-                containerSchema,
-                version,
-            );
-            return await newContainer.attach();
-        } catch (e) {
-            // Error. Keep going.
-        }
-    }
-
-    return Promise.reject(new Error("Could not recreate document"));
-}
+The container is loaded in a paused state, meaning it will not apply the subsequent changes to the data that happened after the generation of that snapshot.  When loaded in this state the container data may be read, but not edited.
 
+`Parameters:`
+
+*   `id`:  The container ID.  This is the same ID used when calling `getContainer`.
+*   `containerSchema`:  The container schema.  This is the same schema used when calling `getContainer`.
+*   `version`:  The version object referencing the version to load from.  The version object can be retrieved via `getContainerVersions`.
+*   `compatibilityMode`:  The compatibility mode.  This is the same compatibility mode used when calling `getContainer`.
+
+`Returns:` A promise which resolves to an object representing the loaded container with a single property:
+
+*   `container`:  The container object.  This is the same type of object as the container object returned by `getContainer`, but is paused in its prior state from the selected version.
+
+### Example
+
+```typescript
+const azureClient = new AzureClient(/* ... */);
+const versions = await azureClient.getContainerVersions(id);
+// Since the versions are sorted in order from newest to oldest, versions[0] will attempt to load the most recent version.
+// If the most recent version is corrupted, we could try again with versions[1] and so on to find the most-recent uncorrupted version.
+const { container } = await azureClient.viewContainerVersion(id, containerSchema, versions[0], "2");
+
+// We can now start reading the data from the container.
+const someData = container.initialObjects.someSharedMap.get("hello");
+
+// With the data extracted, we can inject it into a new uncorrupted container and attach it to start collaborating again.
+const { container: newContainer } = await azureClient.createContainer(containerSchema, "2");
+newContainer.initialObjects.someSharedMap.set("hello", someData);
+const newId = await newContainer.attach();
 ```
 
 ## Key observations
@@ -73,7 +87,7 @@ We aren't recovering (rolling back) existing container. `copyContainer` will giv
 
  New container is initially in `detached` state. We can continue working with detached container, or immediately attach. After calling `attach` we'll get back unique Container ID, representing newly created instance.
 
- ## Post-recovery considerations
+## Post-recovery considerations
 
 When it comes to building use cases around post-recovery scenarios, here are couple of considerations on what application might want do to get its remote collaborators all working on the same container again.