Sdílet prostřednictvím

Azure Resources Graph (ARG) GET/LIST API (Preview)

Rozhraní API ARG GET/LIST je navrženo tak, aby významně snížilo omezení čtení díky přesměrování GET a LIST požadavků na alternativní platformu ARG. Tato akce se dosahuje prostřednictvím inteligentního směrování ovládací roviny, které směřuje požadavky na alternativní platformu, pokud je přítomen specifický parametr. Pokud parametr chybí, požadavky se bezproblémově směrují zpět na původního poskytovatele prostředků a zajišťují flexibilitu.

ARG GET/LIST poskytuje v pohyblivém okně výchozí kvótu 4 tisíc za minutu, uživatele a předplatné, což znamená, že výchozí kvóta 4k za minutu umožňuje provádět až 4 000 požadavků za minutu pomocí těchto rozhraní API. Tato kvóta je vynucována pro každého uživatele a každé předplatné. To znamená:

  • Pokud uživatel A přistupuje k předplatnému X, dostane až 4 000 požadavků za minutu.
  • Pokud uživatel A přistupuje k předplatnému Y, je to samostatná kvóta.
  • Pokud uživatel B přistupuje k předplatnému X, je to také samostatná kvóta.
  • Rozhraní API poskytuje v hlavičce odpovědi hlavičky "x-ms-user-quota-remaining", která označuje zbývající kvótu, a "x-ms-user-quota-resets-after", která označuje čas pro úplné resetování kvóty. Na základě těchto údajů můžete porozumět tomu, jak využíváte kvótu.

Poznámka:

Mějte na paměti, že kvóta Azure Resource Manageru se vztahuje na tato volání. Přečtěte si o limitech Azure Resource Manageru, což jsou nové limity, které Azure Resource Manager sleduje pro veřejný cloud Azure. 

Použití rozhraní API ARG GET/LIST

Pokud chcete použít rozhraní API ARG GET/LIST, nejprve zjistěte, zda váš scénář odpovídá podmínkám uvedeným v pokynech pro omezené požadavky. Pak můžete k příslušným voláním rozhraní GET/LIST API připojit příznak &useResourceGraph=true , který směruje požadavek na tento back-end ARG pro odpověď.

useResourceGraph I když příznak bude fungovat podle očekávání, doporučujeme zaslat e-mailem týmu Azure Resource Graph stručný přehled vašeho scénáře. Pomůžete tak týmu Azure Resource Graphu (ARG) lépe porozumět vašemu případu použití a poskytnout příslušné pokyny.

Tento model výslovného souhlasu byl záměrně zvolen, aby týmu Azure Resource Graphu umožnil lépe porozumět vzorům využití zákazníků a podle potřeby vylepšit.

Projděte si některá známá omezení anejčastější dotazy.

Kontrakt rozhraní API ARG GET/LIST

Získání zdrojového bodu

Tento požadavek se používá k vyhledání jednoho prostředku poskytnutím prostředku D.

Požadavek na získání tradičního bodu:

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

Požadavek na získání bodu ARG:

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

Sbírka předplatného

Tento požadavek slouží k výpisu všech prostředků v rámci jednoho typu prostředku v předplatném.

Požadavek na získání tradiční kolekce předplatného:

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

Získat požadavek na kolekci předplatného ARG:

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

Získání kolekce skupin prostředků

Tento požadavek slouží k výpisu všech prostředků v rámci jednoho typu prostředku ve skupině prostředků.

Požadavek na získání tradičního bodu:

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

ARG GET/LIST Požadavek na ziskání bodu:

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

Poznámka:

Parametr verze rozhraní API je povinný pro všechna volání rozhraní API GET/LIST služby Azure Resource Graph. Hodnota tohoto parametru je však službou ignorována. Bez ohledu na zadanou verzi rozhraní API vrátí ARG vždy výsledky na základě nejnovější obecně dostupné verze (GA) bez verze Preview rozhraní API.

Některé často používané příklady

Scénář: Získání virtuálního počítače pomocí InstanceView

V tomto konkrétním příkladu použijte následující požadavky k získání virtuálního počítače s InstanceView.

Žádost 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

Výpis virtuálních počítačů v rámci skupiny prostředků

V tomto konkrétním příkladu použijte následující požadavky k načtení seznamu virtuálních počítačů ve skupině prostředků.

Žádost 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

Seznam virtuálních počítačů VMSS (Uniform) s InstanceView

V tomto konkrétním příkladu použijte následující požadavek k načtení seznamu VM virtuálních počítačů VMSS s InstanceView. Tento scénář je určený pro virtuální počítač VMSS v flexibilním režimu orchestrace.

Žádost 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

Výpis virtuálního počítače VMSS (Flex) pomocí instanceView

V tomto konkrétním příkladu použijte následující požadavky k načtení seznamu VMSS virtuálních počítačů s InstanceView.

Žádost 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

Seznam účtů úložiště v předplatném

V tomto konkrétním příkladu použijte následující žádosti pro získání seznamu účtů úložiště v předplatném.

Žádost ARG GET/LIST

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

Známá omezení

  • Stav zdraví VM VMSS není aktuálně podporována. Pokud tato data potřebujete, můžete svůj scénář sdílet a navrhnout přidání funkce na našich fórech pro názory.
  • Rozšíření virtuálních počítačů a VMSS – Provozní stavy rozšíření virtuálních počítačů a VMSS nejsou podporovány. Pokud tato data potřebujete, můžete svůj scénář sdílet a navrhnout přidání funkce na našich fórech pro názory.
  • Podporované prostředky – rozhraní API ARG GET/LIST podporuje všechny typy prostředků v rámci tabulek resources a computeresources. Pokud potřebujete typ prostředku, který není součástí těchto tabulek, můžete svůj scénář sdílet a navrhnout přidání funkce na našich fórech pro zpětnou vazbu.
  • Podpora jedné verze rozhraní API – ARG GET/LIST dnes podporuje pouze jednu verzi rozhraní API pro každý typ prostředku, což je obecně nejnovější verze typu, který existuje ve specifikaci rozhraní Azure REST API. Funkce ARG GET/LIST vrátí apiVersion pole v datové části prostředku odpovědi, která označuje verzi typu prostředku, který byl použit při načítání podrobností o prostředku. Volající můžou toto pole použít, aby porozuměli verzi rozhraní API, která se má použít, pokud je relevantní pro jejich scénář.
  • Podpora klientů
    • Rozhraní Azure REST API: Podporováno
    • Azure SDK: Podporovaný ukázkový kód .NET
    • PowerShell: Aktuálně se nepodporuje
    • Azure CLI: V současné době se nepodporuje
    • Azure Portal: Aktuálně se nepodporuje
  • Problematika deserializace klientů
    • Pokud klient k vydávání volání GET používá rozhraní REST API, nemělo by se obecně jednat o deserializaci kvůli rozdílům ve verzích rozhraní API.
    • Pokud klient používá sadu Azure SDK za účelem provádění volání GET díky uvolněným nastavením deserializace napříč všemi jazyky, neměl by být problém s deserializací, pokud nedojde k porušení kontraktu mezi různými verzemi pro cílový typ prostředku.
  • Nezpracovatelná žádost o prostředek
    • Existují vzácné scénáře, kdy ARG GET/LIST nedokáže správně indexovat prostředek, přestože prostředek existuje. Pokud nechcete obětovat kvalitu dat, ARG GET/LIST odmítá obsluhovat volání GET pro tyto prostředky a vrací kód chyby HTTP 422.
    • Klienti ARG GET/LIST by měli považovat HTTP 422 za trvalou chybu. Klienti by měli zopakovat akci tím, že se vrátí zpět k poskytovateli zdrojů (odebráním useResourceGraph=true příznaku). Vzhledem k tomu, že se chyba vztahuje konkrétně na ARG GET/LIST, by použití záložní možnosti u poskytovatelů prostředků mělo vést k úspěchu v rozsahu od začátku do konce (E2E).
  • Podporovaná úroveň konzistence
    • Při použití ARG GET nebo LIST data, která obdržíte, odrážejí nedávné změny s mírným zpožděním – obvykle jen několik sekund – spíše než aktualizace v reálném čase. To se označuje jako "ohraničená nečistost" a zajišťuje rychlé a škálovatelné dotazy a zároveň poskytuje konzistentní a up-tozobrazení dat vašich prostředků Azure. Na rozdíl od přímých volání poskytovatelů prostředků, které zaručují přesnost v reálném čase (silná konzistence), je ARG optimalizován pro výkon s předvídatelnými daty téměř v reálném čase.
    • Ve vrácených odpovědích na dotazy prostředků, ARG GET/LIST poskytuje hlavičku odpovědi x-ms-arg-snapshot-timestamp, která označuje čas, kdy byl vrácený snímek prostředků zaindexován. Hodnota záhlaví je čas UTC ve formátu ISO8601. (Příklad: x-ms-arg-snapshot-timestamp: "2023-01-20T18:55:59.5610084Z").

Ukázkový kód sady SDK

Následující příklad je ukázka kódu .NET pro volání rozhraní API ARG GET/LIST vytvořením ARMClient se zásadou, která přidá příznak useResourceGraph=true ke každému volání:

Nejprve vytvoříme vlastní ArmClientOption s politikou, která přidá příznak na každé volání: useResourceGraph=True

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

Pak vytvoříme ArmClient pomocí vlastních ArmClientOptions:

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

Co když chceme vytvořit ARMClient pomocí výchozího předplatného? Hodnotu klienta ArmClient bychom nastavili na:

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

Volitelně můžete vytvořit výchozího klienta, který nepřidá příznak useResourceGraph, a klientský kód pak zvolí, který klient se použije na základě konkrétních scénářů a potřeb. Uděláte to tak, že použijete následující blok kódu:

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

Pak pomocí této zásady přidejte parametry dotazu pro každý požadavek prostřednictvím klienta:

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

Nejčastější dotazy

  • Jak zajistíte, že odpověď vrátí rozhraní API ARG GET/LIST?

    Existuje několik způsobů, jak zjistit žádost ARG GET/LIST:

    • V těle odpovědi bude vyplněno pole zdrojů, pokud je spravováno pomocí ARG GET/LIST. 
    • ARG GET/LIST/ARG vrátí několik dalších hlaviček odpovědi, z nichž některé jsou:
      • x-ms-arg-snapshot
      • zbývající kvóta uživatele
      • x-ms-limit uživatele se obnovuje po
      • x-ms-resource-graph-request-duration

  • Jak víte, jakou verzi rozhraní API používal ARG GET/LIST?

    Tato hodnota je vrácena v apiVersion poli v odpovědi na zdroj dnes. 

  • Co se stane, když volající volá rozhraní API ARG GET/LIST s příznakem useResourceGraph=true pro prostředek, který ARG GET/LIST nepodporuje?  

    Všechny nepodporované nebo nesměrovatelné požadavky se useResourceGraph=true ignorují a volání se automaticky směruje na poskytovatele prostředků. Uživatel nemusí provádět žádnou akci.  

  • Jaká oprávnění se vyžadují pro dotazování rozhraní API ARG GET/LIST?

    Pro rozhraní API ARG GET/LIST nejsou vyžadována žádná zvláštní oprávnění; Rozhraní API ARG GET/LIST jsou ekvivalentní nativním rozhraním GET API založeným na poskytovateli prostředků, a proto platí standardní RBAC. Volající musí mít alespoň oprávnění KE ČTENÍ k prostředkům nebo oborům, ke kterým se pokouší získat přístup. 

  • Jaká je strategie vrácení zpět, pokud při používání rozhraní API ARG GET/LIST najdeme problémy?  

    Při onboardingu prostřednictvím příznaku useResourceGraph=truese volající může rozhodnout odebrat příznak (nebo) nastavit hodnotu na useResourceGraph=falsea volání se automaticky směruje na poskytovatele prostředků. 

  • Co když se vám při pokusu získat prostředek z ARG GET/LIST, který byl nedávno vytvořen, zobrazí chyba 404 Not Found?

    Jedná se o běžný scénář u mnoha služeb, kde zákazníci vytvářejí prostředky a během 1 až 2 sekund odesílají GET jako součást jiného pracovního postupu zápisu. Zákazníci například vytvoří nový prostředek a hned poté se pokusí vytvořit upozornění na metriku, které tento prostředek monitoruje. Prostředek možná ještě nebyl indexován službou ARG GET/LIST. Existují dva způsoby, jak tuto situaci obejít:

    • Zkuste to znovu na ARG GET/LIST několikrát, dokud nevrátí stavový kód 200. 
    • Zkuste to znovu bez příznaku ARG GET/LIST a vraťte se zpět k poskytovateli zdrojů. Skutečný stavový kód 404 nezasáhne poskytovatele prostředků, protože Azure Resource Manager vrátí chybu přímo, zatímco falešný 404 by měli poskytovatelé prostředků obsloužit, aby získali přesná data.

  • Jaké parametry identifikátoru URI podporuje rozhraní API ARG GET/LIST?

    Rozhraní API ARG GET/LIST podporuje řadu parametrů identifikátoru URI, které pomáhají přizpůsobit a stránkovat výsledky dotazů. Patří mezi ně: Standardní parametry stránkování OData:

    • $top: Určuje počet vrácených záznamů.
    • $skip: Přeskočí zadaný počet záznamů.
    • $skipToken: Používá se k načtení další stránky výsledků ve stránkovaných dotazech.

    Parametry dotazu pro virtuální počítače a virtuální počítače VMSS –

    • statusOnly: statusOnly=true umožňuje načíst stav běhu všech virtuálních počítačů v předplatném.
    • $expand=instanceView: Výraz rozbalení, který má být použit při operaci. InstanceView umožňuje načtení stavu běhu všech virtuálních počítačů, dá se zadat pouze v případě, že je zadána platná možnost $filter.
    • $filter: Možnost systémového dotazu pro filtrování virtuálních počítačů vrácených v odpovědi. Povolená hodnota je virtualMachineScaleSet/id rovná /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}

  • Co mám dělat, když při volání služby Azure Resource Graph dojde k problémům s použitím parametru useResourceGraph?

    Pokud při používání parametru useResourceGraph s ARG dojde k problémům, vytvořte lístek podpory ve službě Azure Resource Graph na webu Azure Portal v části Nápověda a podpora.