After you [build](https://docs.cloud.google.com/vision-ai/docs/build-app.md.txt) and [deploy](https://docs.cloud.google.com/vision-ai/docs/deploy-app.md.txt) apps, you can
create and update these app instances using the Google Cloud console or command line.

## Create an app instance

### REST

To create an app instance, send a POST request by using the
[projects.locations.applications.createApplicationInstances](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.applications/createApplicationInstances.md.txt)
method.


Before using any of the request data,
make the following replacements:

- <var translate="no">PROJECT_NUMBER</var>: Your Google Cloud [project number](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects).
- <var translate="no">LOCATION_ID</var>: The [region](https://cloud.google.com/about/locations) where you are using Agent Platform Vision. For example: `us-central1`, `europe-west4`. See [available regions](https://docs.cloud.google.com/vision-ai/docs/warehouse-supported-regions.md.txt).
- <var translate="no">APPLICATION_ID</var>: The ID of your target application.


HTTP method and URL:

```
POST https://visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID:createApplicationInstances
```


Request JSON body:

```
{
  "applicationInstances": [
    {
      "instance": {
        "inputResources": [
          {
            "consumerNode": "input-stream",
            "inputResource": "projects/PROJECT_NUMBER/locations/LOCATION_ID/clusters/application-cluster-0/streams/STREAM_ID"
          }
        ]
      },
      "instanceId": "INSTANCE_ID"
    },
    {
      "instance": {
         [...]
    },
    [...]
  ]
}
```

To send your request, choose one of these options:

#### curl

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Save the request body in a file named `request.json`,
and execute the following command:

```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID:createApplicationInstances"
```

#### PowerShell

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Save the request body in a file named `request.json`,
and execute the following command:

```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID:createApplicationInstances" | Select-Object -Expand Content
```

You should receive a JSON response similar to the following:

```
{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.visionai.v1.OperationMetadata",
    "createTime": "[...]",
    "Target": "projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID"
    "Verb": "update"
    "apiVersion": "v1"
  },
  "done": false
}
```

<br />

<br />

## Update an app instance

After you create an app and [get an app instance ID](https://docs.cloud.google.com/vision-ai/docs/create-app-instances.md.txt#view-app-output), you can
modify the following app instance resources:

- **Input stream** ^\*^: You can change the input stream asset.
- **Output warehouse asset** : You can update the output asset if you connected to a warehouse and want to write the output to a different warehouse (`corpus`) asset.
- **Output stream** ^\*^: You can overwrite the output stream if you want
  to update the output stream from an auto generated stream to a specific
  stream you create.

  ^\*^ *The input stream and output stream must be under the same
  cluster for the same application instance.*

### REST

To update an app instance, send a POST request by using the
[projects.locations.applications.updateApplicationInstances](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.applications/updateApplicationInstances.md.txt)
method.

The following code sample updates the input stream (`inputResources`), and
all output resources associated with the app instance (`outputResources`).


Before using any of the request data,
make the following replacements:

- <var translate="no">PROJECT</var>: Your Google Cloud [project ID or
  project number](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).
- <var translate="no">LOCATION_ID</var>: The [region](https://cloud.google.com/about/locations) where you are using Agent Platform Vision. For example: `us-central1`, `europe-west4`. See [available regions](https://docs.cloud.google.com/vision-ai/docs/warehouse-supported-regions.md.txt).
- <var translate="no">APPLICATION_ID</var>: The ID of your target application.
- <var translate="no">INSTANCE_NAME</var>: The full resource name of the app instance. For example:
  - `projects/PROJECT/locations/LOCATION_ID/applications/APPLICATION_ID/instances/INSTANCE_ID`
- `inputResources`: The input resource (or resources) for the current application instance. This is an array of objects that contain the following fields:
  - `consumerNode`: The name of graph node who receives the input resource.
  - `inputResource`: The full input resource name.
- `outputResources`: All the output resources associated to one application instance. This is an array of objects that contain the following fields:
  - `outputResource`: The full output resource name.
  - `producerNode`: The name of graph node who produces the output resource name.


HTTP method and URL:

```
POST https://visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID:updateApplicationInstances
```


Request JSON body:

```
{
  "applicationInstances": [
    {
      "instance": {
        "name": "INSTANCE_NAME",
        "inputResources": [
          {
            "consumerNode": "input-stream",
            "inputResource": "projects/PROJECT_NUMBER/locations/LOCATION_ID/clusters/application-cluster-0/streams/STREAM_ID"
          }
        ],
        "outputResources":[
          {
            "outputResource": "projects/PROJECT_NUMBER/locations/LOCATION_ID/corpora/CORPUS_ID/assets/ASSET_ID",
            "producerNode": "warehouse"
          },
          {
            "outputResource": "projects/PROJECT_NUMBER/locations/LOCATION_ID/clusters/application-cluster-0/streams/STREAM_ID",
            "producerNode": "occupancy-count"
          }
        ]
      },
    }
  ],
}
```

To send your request, choose one of these options:

#### curl

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Save the request body in a file named `request.json`,
and execute the following command:

```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID:updateApplicationInstances"
```

#### PowerShell

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Save the request body in a file named `request.json`,
and execute the following command:

```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://visionai.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/applications/APPLICATION_ID:updateApplicationInstances" | Select-Object -Expand Content
```

<br />

<br />

## Manage large scale apps

The deploy and undeploy methods are valid for applications with less than
20 instances. If your app has more than 20 instances you must create and
remove instances incrementally with the API. The recommended workflow is as
follows:

1. Create your app.
2. Add 1-20 experimental instances.
3. Deploy your application.
4. Verify your app works as expected.
5. Use the [`createApplicationInstances`](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.applications/createApplicationInstances.md.txt) method to incrementally add more inputs to the deployed application.
6. Allow app to run.
7. Use the [`deleteApplicationInstances`](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.applications/deleteApplicationInstances.md.txt) method to incrementally remove inputs from deployed applications.
8. Undeploy the application.

> [!CAUTION]
> **Caution:** For a single application there can only be *one* update request running at a time. You are responsible for queueing these types of requests, and performing the necessary retries if there is a failure.