Dela via

AZURE Resources Graph (ARG) GET/LIST API (förhandsversion)

ARG GET/LIST-API:et är utformat för att avsevärt minska LÄS-begränsningen genom att avlasta GET- och LIST-begäranden till en alternativ ARG-plattform. Den här åtgärden uppnås genom intelligent kontrollplansdirigering, som dirigerar begäranden till den alternativa plattformen när en specifik parameter finns. Om parametern saknas dirigeras begäranden sömlöst tillbaka till den ursprungliga resursprovidern, vilket ger flexibilitet.

ARG GET/LIST tillhandahåller en standardkvot på 4 000 per minut, användare och prenumeration i ett rörligt fönster, vilket innebär att standardkvoten på 4 000 per minut gör att du kan göra upp till 4 000 begäranden per minut med hjälp av dessa API:er. Den här kvoten tillämpas per användare och prenumeration. Detta innebär att:

  • Om användare A har åtkomst till prenumeration X får de upp till 4 000 begäranden per minut.
  • Om användare A får åtkomst till prenumeration Y är det en separat kvot.
  • Om användare B har åtkomst till Prenumeration X är det också en separat kvot.
  • API:et innehåller svarshuvudet "x-ms-user-quota-remaining" som anger återstående kvot och "x-ms-user-quota-resets-after" som anger tiden för en fullständig kvotåterställning baserat på vilken du kan förstå din kvotförbrukning.

Anmärkning

Tänk på att Azure Resource Manager-kvoten gäller för dessa anrop. Läs mer om Azure Resource Manager-gränserna, som är de nya gränserna som Azure Resource Manager följer för Azure Public Cloud. 

Använda ARG GET/LIST-API:et

Om du vill använda ARG GET/LIST-API:et ska du först identifiera om ditt scenario matchar de villkor som anges i vägledningen för begränsade begäranden. Du kan sedan lägga till flaggan &useResourceGraph=true i dina tillämpliga GET/LIST API-anrop, som dirigerar begäran till den här ARG-serverdelen för svar.

useResourceGraph Flaggan fungerar som förväntat, men vi rekommenderar att du delar en kort sammanfattning av ditt scenario via e-post till Azure Resource Graph-teamet. Detta hjälper Azure Resource Graph-teamet (ARG) att bättre förstå ditt användningsfall och ge lämplig vägledning.

Den här opt-in-modellen valdes avsiktligt så att Azure Resource Graph-teamet bättre kan förstå kundanvändningsmönster och göra förbättringar efter behov.

Se några kända begränsningar här och vanliga frågor och svar.

ARG GET/LIST API Contract

Hämta resurspunkt

Den här begäran används för att leta upp en enskild resurs genom att tillhandahålla resurs D.

Traditionell begäran om att hämta punkt:

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

Hämta begäran för ARG-punkt:

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

Hämta prenumerationskollektion

Den här begäran används för att visa alla resurser under en enda resurstyp i en prenumeration.

Begäran om hämtning av traditionell prenumerationssamling:

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

Begäran om att hämta ARG-prenumerationssamling:

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

Hämta resursgruppsamling

Den här begäran används för att visa alla resurser under en enda resurstyp i en resursgrupp.

Traditionell begäran om att hämta punkt:

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

ARG GET/LIST Point Get Request:

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

Anmärkning

Parametern API-version är obligatorisk för alla AZURE Resource Graph GET/LIST API-anrop. Värdet för den här parametern ignoreras dock av tjänsten. Oavsett vilken API-version som angetts returnerar ARG alltid resultat baserat på den senaste allmänt tillgängliga (GA) icke-förhandsversion av API:et.

Några exempel som används ofta

Scenario: Hämta virtuell dator (VM) med InstanceView

I det här specifika exemplet använder du följande begäranden för att hämta en virtuell dator med InstanceView.

ARG GET/LIST-begäran

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

Lista virtuella datorer under Resursgrupp

I det här specifika exemplet använder du följande begäranden för att hämta listan över virtuella datorer under resursgruppen.

ARG GET/LIST-begäran

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

Lista VMSS VM (Uniform) med InstanceView

I det här specifika exemplet använder du följande begäran för att hämta listan över virtuella VMSS-datorer med InstanceView. Det här scenariot är för VMSS VM i flexibelt orkestreringsläge.

ARG GET/LIST-begäran

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

Lista VMSS VM (Flex) med InstanceView

I det här specifika exemplet använder du följande begäranden för att hämta listan över virtuella VMSS-datorer med InstanceView.

ARG GET/LIST-begäran

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

Visa en lista över lagringskonton i prenumerationen

I det här specifika exemplet använder du följande begäranden för att hämta listan över lagringskonton i prenumerationen.

ARG GET/LIST-förfrågan

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

Kända begränsningar

  • VMSS VM-hälsostatus stöds inte för närvarande. Om du behöver dessa data kan du dela ditt scenario och föreslå funktionstillägget i våra feedbackforum.
  • VM- och VMSS VM-tillägg – De körande tillstånden för VM- och VMSS VM-tillägg stöds inte. Om du behöver dessa data kan du dela ditt scenario och föreslå funktionstillägget i våra feedbackforum.
  • Resurser som stöds – ARG GET/LIST-API:et stöder alla resurstyper som en del av resources tabellen och computeresources . Om du behöver en resurstyp som inte ingår i dessa tabeller kan du dela ditt scenario och föreslå funktionstillägget i våra feedbackforum.
  • Stöd för enskild API-version – ARG GET/LIST stöder i dag endast en enda API-version för varje resurstyp, vilket vanligtvis är den senaste versionen som inte är förhandsversion av den typ som finns i Azure REST API-specifikationen. FUNKTIONEN ARG GET/LIST returnerar apiVersion fältet i resursnyttolasten för svaret som anger vilken version av resurstypen som användes när resursinformationen hämtades. Anropare kan använda det här fältet för att förstå den API-version som ska användas, om det är relevant för deras scenario.
  • Klientsupport
    • Azure REST API: Stöds
    • Stödd Azure SDK: exempelkod i .NET
    • PowerShell: Stöds för närvarande inte
    • Azure CLI: Stöds för närvarande inte
    • Azure-portalen: Stöds för närvarande inte
  • Problem med klientdeserialisering
    • Om en klient använder REST API för att utfärda GET-anrop bör det vanligtvis inte finnas några problem med deserialisering på grund av skillnader i API-versionen.
    • Om en klient använder Azure SDK för att utfärda GET-anrop, på grund av en avslappnad deserialiseringsinställning på alla språk, bör deserialiseringsproblemet inte vara ett problem, såvida det inte finns kontraktsbrytande ändringar mellan olika versioner för målresurstypen.
  • Resursbegäran som inte kan bearbetas
    • Det finns sällsynta scenarier där ARG GET/LIST inte kan indexera en resurs korrekt, förutom resursens existens. För att inte offra datakvaliteten vägrar ARG GET/LIST att hantera GET-anrop för dessa resurser och returnerar en felkod på HTTP 422.
    • Klienter i ARG GET/LIST bör behandla HTTP 422 som ett permanent fel. Klienter bör försöka igen genom att återgå till resursprovidern (genom att ta bort useResourceGraph=true flaggan). Eftersom felet är specifikt tillämpligt för ARG GET/LIST bör återställning till resursprovidrar resultera i en E2E-framgång.
  • Konsekvensnivå som stöds
    • När du använder ARG GET eller LIST återspeglar de data du får de senaste ändringarna med en liten fördröjning , vanligtvis bara några sekunder, i stället för realtidsuppdateringar. Detta kallas "begränsad inaktuellhet" och garanterar snabba, skalbara frågor samtidigt som det ger en konsekvent och up-todatumvy över dina Azure-resurser. Till skillnad från direkta anrop till resursleverantörer, som garanterar hög konsistens i realtid, optimeras ARG för prestanda med förutsägbar data i realtidsnära format.
    • I svaren för Resource Point Get tillhandahåller ARG GET/LIST ett svarshuvud x-ms-arg-snapshot-timestamp som anger tidsstämpeln när den returnerade resursögonblicksbilden indexerades. Värdet för rubriken är UTC-tid i ISO8601 format. (Ett exempel: "x-ms-arg-snapshot-timestamp" : "2023-01-20T18:55:59.5610084Z").

Exempel på SDK-kod

Följande exempel är ett .NET Code-exempel för att anropa ARG GET/LIST API genom att skapa en ARMClient med en princip som lägger till flaggan useResourceGraph=true i varje anrop:

Först skapar vi anpassade ArmClientOption med en princip som lägger till useResourceGraph=True flaggan per anrop:

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

Sedan skapar vi ArmClient med hjälp av anpassade ArmClientOptions:

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

Vad händer om vi vill skapa en ARMClient med en standardprenumeration? Vi ställer in ArmClient-klientvärdet på:

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

Om du vill skapa en standardklient som inte lägger till useResourceGraph flaggan väljer klientkoden vilken klient som ska användas baserat på det specifika scenariot och behoven. Om du vill göra det använder du följande kodblock:

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

Använd sedan den här principen för att lägga till frågeparametrar för varje begäran via klienten:

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); 
        } 
    } 
}

Vanliga frågor

  • Hur ser du till att svaret returneras av ARG GET/LIST-API:et?

    Det finns några sätt som du kan identifiera när du begär ARG GET/LIST:

    • I svarstexten apiVersion fylls resursfältet i om det hanteras av ARG GET/LIST. 
    • ARG GET/LIST/ARG returnerar flera svarshuvuden, varav några är:
      • x-ms-arg-snapshot
      • x-ms-user-quota-remaining
      • If no contextual change is necessary because it's a technical term, the translation remains as-is: x-ms-user-quota-resets-after
      • x-ms-resource-graph-request-duration

  • Hur vet du vilken API-version som användes av ARG GET/LIST?

    Det här värdet returneras i apiVersion fältet i resurssvaret idag. 

  • Vad händer om en anropare anropar ARG GET/LIST API med useResourceGraph=true flagga för en resurs som inte stöds av ARG GET/LIST?  

    Alla begäranden som inte stöds/icke-routbara ignoreras useResourceGraph=true och anropet dirigeras automatiskt till resursleverantören. Användaren behöver inte vidta några åtgärder.  

  • Vilka behörigheter krävs för att köra frågor mot ARG GET/LIST-API:er?

    Inga särskilda behörigheter krävs för ARG GET/LIST-API:er. ARG GET/LIST-API:er motsvarar interna resursproviderbaserade GET-API:er och därför gäller standard-RBAC. Anropare måste ha minst LÄS-behörighet till resurser/omfång som de försöker komma åt. 

  • Vad är återställningsstrategin om vi hittar problem när vi använder ARG GET/LIST-API:er?  

    Om den registreras via flaggan useResourceGraph=truekan anroparen välja att ta bort flaggan (eller) ange värdet till useResourceGraph=false, och anropet dirigeras automatiskt till resursprovidern. 

  • Vad händer om du får en 404 Not Found när du försöker hämta en resurs från ARG GET/LIST som nyligen skapades?

    Det här är ett vanligt scenario med många tjänster där kunder skapar resurser och omedelbart utfärdar en GET på 1–2 sekunder i ett annat WRITE-arbetsflöde. Kunder kan till exempel skapa en ny resurs och försöker direkt efter att skapa en måttavisering som övervakar den. Resursen kanske inte har indexerats av ARG GET/LIST ännu. Det finns två sätt att kringgå den här situationen:

    • Försök igen på ARG GET/LIST några gånger tills statuskoden 200 returneras. 
    • Försök igen utan ARG GET/LIST-flaggan för att återgå till resursprovidern. True status code 404 träffar inte resursprovidern eftersom Azure Resource Manager returnerar felet direkt, medan en falsk 404 ska hanteras av resursprovidrar för att hämta faktiska data.

  • Vilka URI-parametrar stöds av ARG GET/LIST-API:et?

    ARG GET/LIST-API:et stöder ett antal URI-parametrar för att skräddarsy och paginera frågeresultat. Dessa inkluderar: Standard OData-sidnumreringsparametrar:

    • $top: Anger antalet poster som ska returneras.
    • $skip: Hoppar över det angivna antalet poster.
    • $skipToken: Används för att hämta nästa sida med resultat i sidnumrerade frågor.

    Frågeparametrar för virtuella datorer och virtuella VMSS-datorer –

    • statusOnly: statusOnly=true möjliggör hämtning av körningstidsstatus för alla virtuella datorer i prenumerationen.
    • $expand=instanceView: Expand-uttrycket som ska tillämpas på åtgärden. "instanceView" möjliggör hämtning av körningstidsstatus för alla virtuella datorer. Detta kan bara anges om ett giltigt $filter alternativ har angetts
    • $filter: Systemfrågealternativet för att filtrera virtuella datorer som returneras i svaret. Det tillåtna värdet är virtualMachineScaleSet/id eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}

  • Vad ska jag göra om jag stöter på problem när jag använder parametern useResourceGraph när jag anropar Azure Resource Graph?

    Om du får problem när du använder parametern useResourceGraph med ARG skapar du ett supportärende under Azure Resource Graph-tjänsten i Azure-portalen under Hjälp + support.