Common issues about Python SDK

This doc clarify some common misunderstandings about Python SDK.

How to update an existing resource with create_or_update/begin_create_or_update

An operation named create_or_update/begin_create_or_update of Python SDK usually matches PUT. To update a filed of existing resource, users must do like:

    ...
    # get all fileds of existing resource
    agent_pool = client.agent_pools.get(
        resource_group_name="rg1",
        resource_name="clustername1",
        agent_pool_name="agentpool1",
    )
 
    agent_pool.max_count = 10
    agent_pool.min_count = 1
    # change any filed that you want
    #...
 
    response = client.agent_pools.begin_create_or_update(
        resource_group_name="rg1",
        resource_name="clustername1",
        agent_pool_name="agentpool1",
        parameters=agent_pool,
    ).result()

Users may have confuse: why can't I set the filed directly but have to get the existing resource filed? Here is guideline about PUT:

So the question becomes: Why does PUT has such strange limitations when update existing resource? To explain the question, let us assume special scenarios:

• User A want to delete a field X, so A doesn't set the filed X and think: Now that I don't set X, service shall delete X
• User B want to delete a field X, so B doesn't set the filed X and think: Now that I don't set X, service shall keep X same as before

Why is there such ambiguity? It is caused by the meaning of None(in other language, it may be named null/undefined). None has two kinds of different meaning in nature: delete it or keep it same as before. To eliminate the ambiguity, PUT adopts meaning that delete it so if users want to update existing resource, they have to get all the filed of the resource and update specific feild.