docs(DatasetRefresh): create sample of dataset refresh using API command

[may-hartov]

This pull request introduces comprehensive documentation and examples for triggering and monitoring Power BI dataset refresh operations using the Fabric CLI API command. The main change is the addition of a new guide with PowerShell and Bash scripts, along with cross-linking and navigation updates to make the refresh example easily discoverable.

Dataset Refresh Documentation and Examples:

• Added a new guide refresh_dataset_example.md with detailed instructions and scripts (PowerShell and Bash) for triggering and polling dataset refresh status using Power BI REST API endpoints via the Fabric CLI. The guide covers extracting polling URLs from response headers and handling refresh completion states.
• Updated item_examples.md to reference the new dataset refresh example, making it easier for users to find relevant API usage instructions.

dataset refresh Script:

• Triggers a dataset refresh - Uses the Power BI REST API to initiate an on-demand refresh operation for a specified dataset in a workspace
• Extracts the polling endpoint - Parses the API response headers (Location or RequestId) to obtain the status monitoring URL
• Continuously monitors progress - Polls the refresh status at regular intervals until the operation completes, fails, or times out
• Reports the outcome - Displays real-time status updates and exits with success (Completed) or failure (Failed/Cancelled/TimedOut/Disabled) codes

Documentation Navigation Improvements:

• Added the new "Dataset Refresh Example" page to the mkdocs.yml navigation under Item Management, improving discoverability in the docs sidebar.

Release Notes:

• Created a release note documenting the addition of the dataset refresh API command example.

Doc layout:

[ayeshurun]

semantic model :)

[ayeshurun]

Semantic Model

[ayeshurun]

can it be a child of api's examples?

[ayeshurun]

although it adds some background, i think it is redundant here.

i would suggest to keep this doc concise so it speak to our cli end users.

i would expect of something like

`to refresh semantic model, you can use our api command as follows:

Run refresh on demand

fab api -A powerbi -X post "groups/$WORKSPACE_ID/datasets/$SEMANTIC_MODEL_ID/refreshes"

where $SEMANTIC_MODEL_ID and WORKSPACE_ID are set to ...

Run refresh on demand with params

you can also provide additional params to the refresh job, based on the supported payload documented in here [link to api page], as follows:

REQUEST_BODY='{"retryCount":"1","timeout":"00:20:00"}'

fab api -A powerbi -X post "groups/$WORKSPACE_ID/datasets/$SEMANTIC_MODEL_ID/refreshes" --show_headers -i "$REQUEST_BODY"

Run refresh with polling for completion

REFRESH_RESPONSE=$(fab api -A powerbi -X post "groups/$WORKSPACE_ID/datasets/$SEMANTIC_MODEL_ID/refreshes")

STATUS_CODE=$(echo "$REFRESH_RESPONSE" | jq -r '.status_code // empty')

if [ "$STATUS_CODE" != "202" ]; then
    exit 1
fi

POLLING_ENDPOINT=""
LOCATION=$(echo "$REFRESH_RESPONSE" | jq -r '.headers.Location // empty')
if [ -n "$LOCATION" ]; then
    POLLING_ENDPOINT=$(echo "$LOCATION" | sed -n 's|.*https\?://[^/]*/v1\.0/myorg/\(.*\)|\1|p' | xargs)
fi

if [ -z "$POLLING_ENDPOINT" ]; then
    REFRESH_REQUEST_ID=$(echo "$REFRESH_RESPONSE" | jq -r '.headers.RequestId // empty')
    if [ -n "$REFRESH_REQUEST_ID" ]; then
         POLLING_ENDPOINT="groups/$WORKSPACE_ID/datasets/$SEMANTIC_MODEL_ID/refreshes/$REFRESH_REQUEST_ID"
    fi
fi

if [ -z "$POLLING_ENDPOINT" ]; then
    exit 1
fi

while true; do
    sleep "$POLLING_INTERVAL"
    
    STATUS_RESPONSE=$(fab api -A powerbi "$POLLING_ENDPOINT" --show_headers)
    
    GET_STATUS_CODE=$(echo "$STATUS_RESPONSE" | jq -r '.status_code // empty')
    
    if [ "$GET_STATUS_CODE" != "200" ] && [ "$GET_STATUS_CODE" != "202" ]; then
        echo "$STATUS_RESPONSE"
    fi
    
    EXTENDED_STATUS=$(echo "$STATUS_RESPONSE" | jq -r '.text.extendedStatus // empty')
    if [ -n "$EXTENDED_STATUS" ]; then
        STATUS="$EXTENDED_STATUS"
    else
        STATUS=$(echo "$STATUS_RESPONSE" | jq -r '.text.status // empty')
    fi
    
    
    case "$STATUS" in
        "Completed")
            exit 0
            ;;
        "Failed"|"Cancelled"|"Disabled"|"TimedOut")
            echo "$STATUS_RESPONSE"
            exit 1
            ;;
        "NotStarted"|"InProgress"|"Unknown")
            # Continue polling
            ;;
        *)
            echo "$STATUS_RESPONSE"
            exit 1
            ;;
    esac
done