operations.md

Calling Operations with Your Typescript Client

AutoRest provides asynchronous method overloads for each service operation. Depending on your swagger definition, operations can be accessed through operation groups (TODO: link to swagger docs) on the client, or directly on the client.

Operation Group vs No Operation Group

If your swagger defines an operation group for your operation (for example, in this swagger, the operation list is part of operation group application), you would access the operation through client.application.list().

If there's no operation group, as in this case, you would access the operation directly from the client itself, i.e. client.getDog().

Regular Operations

When calling our async operations, we go through our client

import { DefaultAzureCredential } from "@azure/identity";
import { PetsClient } from "@azure/pets";

const client: PetsClient = new PetsClient(new DefaultAzureCredential());
const dog = await client.getDog();

Long Running Operations

Long-running operations are operations which consist of an initial request sent to the service to start an operation, followed by polling the service at intervals to determine whether the operation has completed or failed, and if it has succeeded, to get the result.

In concurrence with our typescript guidelines, all of our long running operations are prefixed with begin, to signify the starting of the long running operation.

For our example, we will use the long running operation generated from this swagger. Let's say we generated this swagger with package name @azure/lro.

By default, our async long running operations return an Poller polling object, though there are ways of changing this. Calling .pollUntilDone() on the poller will wait until the long running operation finishes then return the final result.

import { DefaultAzureCredential } from "@azure/identity";
import { Product, PollingPagingExampleClient } from "@azure/lro";

const client: PollingPagingExampleClient = new PollingPagingExampleClient(new DefaultAzureCredential());

const inputProduct: Product = {
    id: 1;
    name: "My Polling example"
};

const poller = await client.beginBasicPolling(inputProduct);
const outputProduct = await poller.pollUntilDone();

Paging Operations

A paging operation pages through lists of data, returning an iterator for the items. Network calls get made when users start iterating through the output, not when the operation is initially called.

For our example, we will use the long running operation generated from this swagger. Let's say we generated this swagger with package name @azure/paging.

By default, our async paging operations return an PagedAsyncIterableIterator pager. Since network calls aren't made until starting to page, our generated operation is synchronous, and there's no need to wait the initial call to the function. Since network calls are made when iterating, we have to do async looping.

import { DefaultAzureCredential } from "@azure/identity";
import { PollingPagingExampleClient } from "@azure/paging";

const client: PollingPagingExampleClient = new PollingPagingExampleClient(new DefaultAzureCredential());

const pager = client.basicPaging();
for await (const product of pager) {
    console.log(`${product.id}, ${product.name}`);
}

Advanced: LRO + paging

We also support generating a long running paging operation. In this case, we return a poller from the operation, and the final result from the poller is a pager that pages through the final lists of data.