Add excluded locations on client and request levels

[allenkim0129]

This change will add excluded locations on client and request levels.

Design doc: https://microsoft-my.sharepoint.com/:w:/p/allekim/EWf4tc65_f9GiOv9aD2XkLMBD9h2ZAAXCcFTKghjutvqcg?e=AlD8w1

On Client level:

def excluded_locations_client_level_sample():
    preferred_locations = ['West US 3', 'West US', 'East US 2']
    excluded_locations = ['West US 3', 'West US']
    client = CosmosClient(
                HOST,
                MASTER_KEY,
                preferred_locations=preferred_locations,
                excluded_locations=excluded_locations
    )

    db = client.create_database(DATABASE_ID)
    container = db.create_container(id=CONTAINER_ID, partition_key=PARTITION_KEY)

    # For write operations with single master account, write endpoint will be the default endpoint,
    # since preferred_locations or excluded_locations are ignored and used
    container.create_item(get_test_item(0))

    # For read operations, read endpoints will be 'preferred_locations' - 'excluded_locations'.
    # In our sample, ['West US 3', 'West US', 'East US 2'] - ['West US 3', 'West US'] => ['East US 2'],
    # therefore 'East US 2' will be the read endpoint, and items will be read from 'East US 2' location
    item = container.read_item(item='Item_0', partition_key='Item_0')

• Note: During client creation, excluded locations can be set by using the excluded_locations parameter. This set will filter any existing preferred locations. If excluded locations filtered all preferred locations, Cosmos DB will use the default endpoints.

On Request level:

def excluded_locations_request_level_sample():
    preferred_locations = ['West US 3', 'West US', 'East US 2']
    excluded_locations_on_client = ['West US 3', 'West US']
    excluded_locations_on_request = ['West US 3']
    client = CosmosClient(
                HOST,
                MASTER_KEY,
                preferred_locations=preferred_locations,
                excluded_locations=excluded_locations_on_client
    )

    db = client.create_database(DATABASE_ID)
    container = db.create_container(id=CONTAINER_ID, partition_key=PARTITION_KEY)

    # For write operations with single master account, write endpoint will be the default endpoint,
    # since preferred_locations or excluded_locations are ignored and used
    container.create_item(get_test_item(0))

    # For read operations, read endpoints will be 'preferred_locations' - 'excluded_locations'.
    # However, in our sample, since the excluded_locations` were passed with the read request, the `excluded_location`
    # will be replaced with the locations from request, ['West US 3']. The `excluded_locations` on request always takes
    # the highest priority!
    # With the excluded_locations on request, the read endpoints will be ['West US', 'East US 2']
    #   ['West US 3', 'West US', 'East US 2'] - ['West US 3'] => ['West US', 'East US 2']
    # Therefore, items will be read from 'West US' or 'East US 2' location
    item = container.read_item(item='Item_0', partition_key='Item_0', excluded_locations=excluded_locations_on_request)

• Note: The excluded locations on requests level can be used by passing excluded_locations parameters along with any other parameters for Container level APIs. This excluded_location parameter will override the existing exlcuded locations on client level. This means also means that if a user can manupilate the client level excluded locations for the specific request. Moreover, if a user wants to skip all client level excluded locations, the user can simply pass an empty list [] of excluded locations to skip all excluded location filters.

Client level API works with excluded_location(11 APIs):

• read_item
• read_all_items
• query_items_change_feed
• query_items
• replace_item
• upsert_item
• create_item
• patch_item
• execute_item_batch
• delete_item
• delete_all_items_by_partition_key

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[azure-sdk]

API change check

APIView has identified API level changes in this PR and created following API reviews.

azure-cosmos

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

I created a new PR since there were some conflict with branch merges which ended up including more reviewer than required.

Previous PR with comments: #40298

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[allenkim0129]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).