Condividi tramite

Azure Resources Graph (ARG) GET/LIST API

L'API GET/LIST di ARG è progettata per ridurre significativamente la limitazione delle richieste READ eseguendo l'offload delle richieste GET e LIST a una piattaforma ARG alternativa. Questa azione viene eseguita tramite il routing intelligente del piano di controllo, che indirizza le richieste alla piattaforma alternativa quando è presente un parametro specifico. Se il parametro è assente, le richieste vengono reindirizzate senza problemi al provider di risorse originale, garantendo flessibilità.

ARG GET/LIST fornisce una quota predefinita di 4.000 richieste al minuto, utente e sottoscrizione, in una finestra mobile, il che significa che la quota predefinita di 4k al minuto consente di effettuare fino a 4.000 richieste al minuto usando queste API. Questa quota viene applicata per utente per ogni sottoscrizione. Questo significa che:

  • Se l'utente A accede alla sottoscrizione X, arrivano fino a 4.000 richieste al minuto.
  • Se l'utente A accede alla sottoscrizione Y, si tratta di una quota separata.
  • Se l'utente B accede alla sottoscrizione X, si tratta anche di una quota separata.
  • L'API fornisce un'intestazione di risposta "x-ms-user-quota-remaining" che indica la quota rimanente e "x-ms-user-quota-resets-after" che indica il tempo per una reimpostazione della quota completa in base alla quale è possibile comprendere l'utilizzo della quota.

Annotazioni

Tenere presente che la quota di Azure Resource Manager si applica a queste chiamate. Informazioni sui limiti di Azure Resource Manager, ovvero i nuovi limiti che Azure Resource Manager segue per il cloud pubblico di Azure. 

Uso dell'API GET/LIST di ARG

Per usare l'API ARG GET/LIST, identificare prima di tutto se lo scenario corrisponde alle condizioni indicate nelle linee guida per le richieste limitate. È quindi possibile aggiungere il flag &useResourceGraph=true alle chiamate API GET/LIST applicabili, che instradano la richiesta a questo back-end ARG per la risposta.

È necessario contattare il gruppo di prodotti ARG inviando un messaggio di posta elettronica al team di Azure Resource Graph che condivide una breve panoramica dello scenario e il team ARG verrà contattato con i passaggi successivi.

Questo modello di consenso esplicito è stato scelto deliberatamente per consentire al team di Azure Resource Graph di comprendere meglio i modelli di utilizzo dei clienti e apportare miglioramenti in base alle esigenze.

Fare riferimento ad alcune limitazioni note qui e alle domande frequenti.

Contratto API ARG GET/LIST

Recupero del punto di risorsa

Questa richiesta viene usata per cercare una singola risorsa fornendo la risorsa D.

Richiesta get punto tradizionale:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion}

Richiesta get punto ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion}&useResourceGraph=true

Recupero raccolta sottoscrizioni

Questa richiesta viene usata per elencare tutte le risorse in un singolo tipo di risorsa in una sottoscrizione.

Richiesta get della raccolta di sottoscrizioni tradizionale:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}

Richiesta get della raccolta di sottoscrizioni ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true

Recupero raccolta gruppi di risorse

Questa richiesta viene usata per elencare tutte le risorse in un singolo tipo di risorsa in un gruppo di risorse.

Richiesta get punto tradizionale:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}

Richiesta Get/LIST Point Get di ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true

Annotazioni

Il parametro API-version è obbligatorio per tutte le chiamate API GET/LIST di Azure Resource Graph. Tuttavia, il valore di questo parametro viene ignorato dal servizio. Indipendentemente dalla versione api specificata, ARG restituisce sempre i risultati in base alla versione disponibile a livello generale più recente non di anteprima dell'API.

Alcuni esempi usati di frequente

Scenario: Ottenere una macchina virtuale (VM) con InstanceView

Per questo esempio specifico, usare le richieste seguenti per ottenere una macchina virtuale con InstanceView.

Richiesta ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines/{vm}?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true

Elencare le macchine virtuali in ResourceGroup

Per questo esempio specifico, usare le richieste seguenti per recuperare l'elenco di macchine virtuali nel gruppo di risorse.

Richiesta ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true

Elencare vm vm (uniform) con InstanceView

Per questo esempio specifico, usare la richiesta seguente per recuperare l'elenco di macchine virtuali del set di scalabilità di macchine virtuali con InstanceView. Questo scenario riguarda la macchina virtuale VMSS in modalità di orchestrazione flessibile.

Richiesta ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true

Elencare una macchina virtuale VMSS (Flex) con InstanceView

Per questo esempio specifico, usare le richieste seguenti per recuperare l'elenco di macchine virtuali del set di scalabilità di macchine virtuali con InstanceView.

Richiesta ARG GET/LIST

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$filter='virtualMachineScaleSet/id' eq '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}'&$expand=instanceView&useResourceGraph=true

Elencare gli account di archiviazione nella sottoscrizione

Per questo esempio specifico, usare le richieste seguenti per recuperare l'elenco di account di archiviazione nella sottoscrizione.

Richiesta ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.storage/storageAccounts?api-version=2024-01-01&useResourceGraph=true

Limitazioni note

  • Lo stato di integrità della macchina virtuale del set di scalabilità di macchine virtuali non è attualmente supportato. Se sono necessari questi dati, è possibile condividere lo scenario e proporre l'aggiunta di funzionalità nei forum di feedback.
  • Estensioni vm e VMSS: gli stati in esecuzione delle estensioni vm e VMSS non sono supportati. Se sono necessari questi dati, è possibile condividere lo scenario e proporre l'aggiunta di funzionalità nei forum di feedback.
  • Risorse supportate : l'API ARG GET/LIST supporta tutti i tipi di risorse come parte della resources tabella e computeresources . Se è necessario un tipo di risorsa che non fa parte di queste tabelle, è possibile condividere lo scenario e proporre l'aggiunta di funzionalità nei forum di feedback.
  • Supporto della versione dell'API singola : attualmente ARG GET/LIST supporta solo una singola versione DELL'API per ogni tipo di risorsa, che in genere è la versione non di anteprima più recente del tipo presente nella specifica dell'API REST di Azure. La funzionalità ARG GET/LIST restituisce il apiVersion campo nel payload della risorsa della risposta che indica la versione del tipo di risorsa usato durante il recupero dei dettagli della risorsa. I chiamanti possono applicare questo campo per comprendere la versione dell'API da usare, se pertinente per il relativo scenario.
  • Supporto client
    • API REST di Azure: supportata
    • Azure SDK: codice .NET di esempio supportato
    • PowerShell: attualmente non supportato
    • Interfaccia della riga di comando di Azure: attualmente non supportata
    • Portale di Azure: attualmente non supportato
  • Problemi di deserializzazione client
    • Se un client usa l'API REST per eseguire chiamate GET, in genere non dovrebbe esserci alcun problema relativo alla deserializzazione a causa delle differenze di versione dell'API.
    • Se un client usa Azure SDK per eseguire chiamate GET, a causa di un'impostazione di deserializzazione rilassata in tutti i linguaggi, il problema di deserializzazione non deve essere un problema, a meno che non siano presenti modifiche di rilievo del contratto tra versioni diverse per il tipo di risorsa di destinazione.
  • Richiesta di risorsa non elaborabile
    • Esistono rari scenari in cui ARG GET/LIST non è in grado di indicizzare correttamente una risorsa, diversa dall'esistenza della risorsa. Per non sacrificare la qualità dei dati, ARG GET/LIST rifiuta di gestire le chiamate GET per queste risorse e restituisce un codice di errore HTTP 422.
    • I client di ARG GET/LIST devono considerare HTTP 422 come errore permanente. I client devono riprovare eseguendo il fallback al provider di risorse (rimuovendo useResourceGraph=true il flag). Poiché l'errore è applicabile in modo specifico a ARG GET/LIST, il fallback ai provider di risorse dovrebbe comportare un esito positivo di E2E.
  • Livello di coerenza supportato
    • Quando si usa ARG GET o LIST, i dati ricevuti riflettono le modifiche recenti con un lieve ritardo, in genere solo pochi secondi, anziché aggiornamenti in tempo reale. Questa operazione è nota come "decadimento ristretto" e garantisce query veloci e scalabili, pur offrendo una visualizzazione coerente e up-to-date delle risorse di Azure. A differenza delle chiamate dirette ai provider di risorse, che garantiscono l'accuratezza in tempo reale (coerenza assoluta), ARG è ottimizzato per le prestazioni con dati prevedibili e quasi in tempo reale.
    • Nelle risposte Get del punto di risorsa, ARG GET/LIST fornisce un'intestazione di risposta x-ms-arg-snapshot-timestamp che indica il timestamp quando è stato indicizzato lo snapshot della risorsa restituita. Il valore dell'intestazione è l'ora UTC nel formato ISO8601. Ad esempio, "x-ms-arg-snapshot-timestamp" : "2023-01-20T18:55:59.5610084Z").

Codice SDK di esempio

L'esempio seguente è un esempio di codice .NET per chiamare l'API GET/LIST di ARG creando un ARMClient con criteri che aggiunge il flag useResourceGraph=true a ogni chiamata:

Prima di tutto, creiamo armClientOption personalizzato con criteri che aggiungono il useResourceGraph=True flag per chiamata:

var armClientOptions = new ArmClientOptions(); armClientOptions.AddPolicy(new ArgGetListHttpPipelinePolicy(), HttpPipelinePosition.PerCall);

Viene quindi creato ArmClient usando armClientOptions personalizzato:

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), null, armClientOptions);

Cosa accade se si vuole creare un armClient usando una sottoscrizione predefinita? Il valore del client ArmClient verrà impostato su:

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), defaultSubId, armClientOptions);

Facoltativamente, per creare un client predefinito che non aggiunge il useResourceGraph flag, il codice client sceglie il client da usare in base allo scenario e alle esigenze specifiche. A tale scopo, usare il blocco di codice seguente:

ArmClient defaultClient = new ArmClient(new DefaultAzureCredential(), null, new ArmClientOptions());

Usare quindi questo criterio per aggiungere parametri di query per ogni richiesta tramite il client:

internal class ArgGetListHttpPipelinePolicy : HttpPipelineSynchronousPolicy 

{ 
    private static const string UseResourceGraph = "useResourceGraph"; 
    public override void OnSendingRequest(HttpMessage message) 

    { 
        // Adds the required query parameter to explicitly query ARG GET/LIST if the flag is not already present 
        if (!message.Request.Uri.ContainsQuery(UseResourceGraph)) 
        { 
          message.Request.Uri.AppendQuery(UseResourceGraph, bool.TrueString); 
        } 
    } 
}

Domande frequenti

  • Come assicurarsi che la risposta venga restituita dall'API ARG GET/LIST?

    Esistono alcuni modi per identificare quando una richiesta ARG GET/LIST:

    • Nel corpo della risposta il apiVersion campo delle risorse verrà popolato, se servito da ARG GET/LIST. 
    • ARG GET/LIST/ARG restituisce altre intestazioni di risposta, alcune delle quali:
      • x-ms-arg-snapshot
      • x-ms-user-quota-remaining
      • x-ms-user-quota-resets-after
      • x-ms-resource-graph-request-duration

  • Come si sa quale versione dell'API è stata usata da ARG GET/LIST?

    Questo valore viene restituito nel apiVersion campo nella risposta alla risorsa. 

  • Cosa accade se un chiamante chiama l'API GET/LIST di ARG con useResourceGraph=true flag per una risorsa non supportata da ARG GET/LIST?  

    Tutte le richieste non supportate/non indirizzabili generano useResourceGraph=true un'operazione ignorata e la chiamata viene indirizzata automaticamente al provider di risorse. L'utente non deve eseguire alcuna azione.  

  • Quali autorizzazioni sono necessarie per l'esecuzione di query sulle API GET/LIST di ARG?

    Non sono necessarie autorizzazioni speciali per le API GET/LIST di ARG; Le API GET/LIST di ARG sono equivalenti alle API GET basate su provider di risorse native e pertanto si applica il controllo degli accessi in base al ruolo standard. I chiamanti devono avere almeno le autorizzazioni di lettura per le risorse o gli ambiti a cui tentano di accedere. 

  • Qual è la strategia di rollback, se vengono riscontrati problemi durante l'uso delle API GET/LIST di ARG?  

    Se è stato eseguito l'onboarding tramite il flag useResourceGraph=true, il chiamante può scegliere di rimuovere il flag (o) impostare il valore su useResourceGraph=falsee la chiamata viene instradata automaticamente al provider di risorse. 

  • Cosa accade se si ottiene un errore 404 Non trovato quando si tenta di ottenere una risorsa da ARG GET/LIST creata di recente?

    Questo è uno scenario comune con molti servizi in cui i clienti creano risorse e generano immediatamente un GET in 1-2 secondi parte di un altro flusso di lavoro WRITE. Ad esempio, i clienti creano una nuova risorsa e subito dopo aver tentato di creare un avviso di metrica che lo monitora. La risorsa potrebbe non essere stata ancora indicizzata da ARG GET/LIST. Esistono due modi per risolvere questa situazione:

    • Riprovare in ARG GET/LIST alcune volte fino a quando non restituisce il codice di stato 200. 
    • Riprovare senza flag GET/LIST ARG per eseguire il fallback nel provider di risorse. Il codice di stato true 404 non raggiunge il provider di risorse perché Azure Resource Manager restituisce direttamente l'errore, mentre un falso 404 deve essere gestito dai provider di risorse per ottenere i dati effettivi.

  • Quali parametri URI sono supportati dall'API GET/LIST di ARG?

    L'API ARG GET/LIST supporta un intervallo di parametri URI per personalizzare e impaginare i risultati delle query. Questi includono: Parametri di paginazione OData standard:

    • $top: specifica il numero di record da restituire.
    • $skip: ignora il numero specificato di record.
    • $skipToken: usato per recuperare la pagina successiva dei risultati nelle query impaginate.

    Parametri di query per macchine virtuali e VMSS :

    • statusOnly: statusOnly=true abilita il recupero dello stato di runtime di tutte le macchine virtuali nella sottoscrizione.
    • $expand=instanceView: espressione di espansione da applicare all'operazione. 'instanceView' abilita il recupero dello stato di runtime di tutte le macchine virtuali, che può essere specificato solo se viene specificata un'opzione di $filter valida
    • $filter: opzione di query di sistema per filtrare le macchine virtuali restituite nella risposta. Il valore consentito è virtualMachineScaleSet/id eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}

  • Cosa è necessario fare se si verificano problemi durante l'uso del parametro useResourceGraph quando si chiama Azure Resource Graph?

    Se si verificano problemi durante l'uso del useResourceGraph parametro con ARG, creare un ticket di supporto nel servizio Azure Resource Graph nel portale di Azure in Guida e supporto tecnico.