Szybki start: tworzenie aplikacji .NET Framework lub Core za pomocą konta interfejsu API języka Gremlin w usłudze Azure Cosmos DBQuickstart: Build a .NET Framework or Core application using the Azure Cosmos DB Gremlin API account

Azure Cosmos DB to rozproszona globalnie, wielomodelowa usługa bazy danych firmy Microsoft.Azure Cosmos DB is Microsoft's globally distributed multi-model database service. Dzięki dystrybucji globalnej i możliwości skalowania poziomego w usłudze Azure Cosmos DB możesz szybko tworzyć i za pomocą zapytań badać bazy danych dokumentów, par klucz/wartość oraz grafów.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Ten przewodnik Szybki Start przedstawia sposób Azure Cosmos DB tworzenia konta interfejsu API Gremlin , bazy danych i grafu (kontenera) przy użyciu Azure Portal.This quickstart demonstrates how to create an Azure Cosmos DB Gremlin API account, database, and graph (container) using the Azure portal. Następnie aplikacja konsoli utworzona za pomocą sterownika open source Gremlin.Net zostanie skompilowana i uruchomiona.You then build and run a console app built using the open-source driver Gremlin.Net.

Wymagania wstępnePrerequisites

Jeśli nie masz jeszcze zainstalowanego programu Visual Studio 2019, możesz pobrać i korzystać bezpłatnie z programu Visual Studio 2019 Community Edition.If you don't already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Podczas instalacji programu Visual Studio upewnij się, że jest włączona opcja Programowanie na platformie Azure.Make sure that you enable Azure development during the Visual Studio setup.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.If you don't have an Azure subscription, create a free account before you begin.

Tworzenie konta bazy danychCreate a database account

  1. W nowym oknie przeglądarki zaloguj się do witryny Azure Portal.In a new browser window, sign in to the Azure portal.

  2. Kliknij kolejno pozycje Utwórz zasób > Bazy danych > Azure Cosmos DB.Click Create a resource > Databases > Azure Cosmos DB.

    Okienko „Bazy danych” w witrynie Azure Portal

  3. Na stronie Tworzenie konta usługi Azure Cosmos DB wprowadź ustawienia nowego konta usługi Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    UstawienieSetting WartośćValue OpisDescription
    SubscriptionSubscription Twoja subskrypcjaYour subscription Wybierz subskrypcję platformy Azure, której chcesz użyć dla tego konta usługi Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupa zasobówResource Group Tworzenie nowego elementuCreate new

    Następnie wprowadź taką samą unikatową nazwę, która została podana jako identyfikatorThen enter the same unique name as provided in ID
    Wybierz pozycjęUtwórz nowy.Select Create new. Następnie wprowadź nazwę nowej grupy zasobów dla swojego konta.Then enter a new resource-group name for your account. Dla uproszczenia użyj takiej samej nazwy jak identyfikator.For simplicity, use the same name as your ID.
    Nazwa kontaAccount Name Podaj unikatową nazwęEnter a unique name Wprowadź unikatową nazwę do identyfikacji konta usługi Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Ponieważ adres documents.azure.com jest dołączany do podanego identyfikatora w celu utworzenia identyfikatora URI, użyj unikatowego identyfikatora.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    Identyfikator może zawierać tylko małe litery, cyfry i znaki łącznika (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Musi mieć długość od 3 do 31 znaków.It must be between 3 and 31 characters in length.
    interfejs APIAPI Gremlin (graf)Gremlin (graph) Interfejs API określa typ konta do utworzenia.The API determines the type of account to create. Usługa Azure Cosmos DB oferuje pięć interfejsów API: Core(SQL) dla baz danych dokumentów, Gremlin dla baz danych wykresów, MongoDB dla baz danych dokumentów, Azure Table i Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. Obecnie dla każdego interfejsu API należy utworzyć oddzielne konto.Currently, you must create a separate account for each API.

    Wybierz pozycję Gremlin (graf) , ponieważ w podręczniku Szybki start tworzysz tabelę, która współdziała z interfejsem API języka Gremlin.Select Gremlin (graph) because in this quickstart you are creating a table that works with the Gremlin API.

    Dowiedz się więcej o interfejsie API programu Graph.Learn more about the Graph API.
    LocationLocation Wybierz region najbliżej Twoich użytkownikówSelect the region closest to your users Wybierz lokalizację geograficzną, w której będzie hostowane konto usługi Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Użyj lokalizacji znajdującej się najbliżej Twoich użytkowników, aby zapewnić im najszybszy dostęp do danych.Use the location that's closest to your users to give them the fastest access to the data.

    Wybierz pozycję Przeglądanie+tworzenie.Select Review+Create. Możesz pominąć sekcje Sieć i Tagi.You can skip the Network and Tags section.

    Sekcja nowe konto dla Azure Cosmos DB

  4. Tworzenie konta potrwa kilka minut.The account creation takes a few minutes. Poczekaj, aż w portalu zostanie wyświetlona strona Gratulacje! Konto usługi Azure Cosmos DB zostało utworzone.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

    Okienko Powiadomienia w witrynie Azure Portal

Dodawanie grafuAdd a graph

Teraz możesz użyć narzędzia Eksplorator danych w witrynie Azure Portal, aby utworzyć bazę danych grafów.You can now use the Data Explorer tool in the Azure portal to create a graph database.

  1. Wybierz pozycję Eksplorator danych > Nowy Graf.Select Data Explorer > New Graph.

    Obszar Dodaj graf jest wyświetlany po prawej stronie i konieczne może być przewinięcie w prawo w celu wyświetlenia go.The Add Graph area is displayed on the far right, you may need to scroll right to see it.

    Eksplorator danych witryny Azure Portal, strona Dodaj graf

  2. Na stronie Dodaj graf wprowadź ustawienia dla nowego grafu.In the Add graph page, enter the settings for the new graph.

    UstawienieSetting Sugerowana wartośćSuggested value OpisDescription
    Identyfikator bazy danychDatabase ID sample-databasesample-database Wprowadź sample-database jako nazwę nowej bazy danych.Enter sample-database as the name for the new database. Nazwy baz danych muszą zawierać od 1 do 255 znaków i nie mogą zawierać znaków / \ # ? ani mieć spacji na końcu.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    PrzepływnośćThroughput 400 jednostek żądania400 RUs Zmień przepływność na 400 jednostek żądania na sekundę (RU/s).Change the throughput to 400 request units per second (RU/s). Jeśli chcesz zmniejszyć opóźnienie, możesz później przeskalować przepływność w górę.If you want to reduce latency, you can scale up the throughput later.
    Identyfikator grafuGraph ID sample-graphsample-graph Wprowadź sample-graph jako nazwę nowej kolekcji.Enter sample-graph as the name for your new collection. W przypadku nazw grafów obowiązują takie same wymagania dotyczące znaków jak dla identyfikatorów baz danych.Graph names have the same character requirements as database IDs.
    Klucz partycjiPartition Key /pk/pk Wszystkie konta Cosmos DB muszą mieć klucz partycji w poziomie.All Cosmos DB accounts need a partition key to horizontally scale. Dowiedz się, jak wybrać odpowiedni klucz partycji w artykule Partycjonowanie danych grafu.Learn how to select an appropriate partition key in the Graph Data Partitioning article.
  3. Po wypełnieniu formularza wybierz przycisk OK.Once the form is filled out, select OK.

Klonowanie przykładowej aplikacjiClone the sample application

Teraz sklonujemy aplikację interfejsu API języka Gremlin z repozytorium GitHub, ustawimy parametry połączenia i uruchomimy ją.Now let's clone a Gremlin API app from GitHub, set the connection string, and run it. Zobaczysz, jak łatwo jest pracować programowo z danymi.You'll see how easy it is to work with data programmatically.

  1. Otwórz wiersz polecenia, utwórz nowy folder o nazwie git-samples, a następnie zamknij wiersz polecenia.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Otwórz okno terminalu usługi Git, na przykład git bash, i użyj polecenia cd, aby przejść do nowego folderu instalacji aplikacji przykładowej.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Uruchom następujące polecenie w celu sklonowania przykładowego repozytorium.Run the following command to clone the sample repository. To polecenie tworzy kopię przykładowej aplikacji na komputerze.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
    
  4. Następnie otwórz program Visual Studio i otwórz plik rozwiązania.Then open Visual Studio and open the solution file.

  5. Przywróć pakiety NuGet w projekcie.Restore the NuGet packages in the project. Powinny one obejmować sterownik Gremlin.Net, a także pakiet Newtonsoft.Json.This should include the Gremlin.Net driver, as well as the Newtonsoft.Json package.

  6. Sterownik Gremlin.Net możesz także zainstalować ręcznie, za pomocą menedżera pakietów NuGet lub narzędzia wiersza polecenia nuget:You can also install the Gremlin.Net driver manually using the Nuget package manager, or the nuget command-line utility:

    nuget install Gremlin.Net
    

Przeglądanie koduReview the code

Ten krok jest opcjonalny.This step is optional. Jeśli chcesz dowiedzieć się, jak zasoby bazy danych są tworzone w kodzie, możesz przejrzeć poniższe fragmenty kodu.If you're interested in learning how the database resources are created in the code, you can review the following snippets. W przeciwnym razie możesz od razu przejść do sekcji Aktualizowanie parametrów połączenia.Otherwise, you can skip ahead to Update your connection string.

Wszystkie poniższe fragmenty kodu pochodzą z pliku Program.cs.The following snippets are all taken from the Program.cs file.

  • Ustaw parametry połączenia na podstawie konta utworzonego powyżej (wiersz 19):Set your connection parameters based on the account created above (Line 19):

    private static string hostname = "your-endpoint.gremlin.cosmosdb.azure.com";
    private static int port = 443;
    private static string authKey = "your-authentication-key";
    private static string database = "your-database";
    private static string collection = "your-graph-container";
    
  • Polecenia języka Gremlin do wykonania są wyświetlane w postaci słownika (wiersz 26):The Gremlin commands to be executed are listed in a Dictionary (Line 26):

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    {
        { "Cleanup",        "g.V().drop()" },
        { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
        { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
        { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
        { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
        { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
        { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
        { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
        { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
        { "CountVertices",  "g.V().count()" },
        { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
        { "Project",        "g.V().hasLabel('person').values('firstName')" },
        { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
        { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
        { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
        { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
        { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
        { "CountEdges",     "g.E().count()" },
        { "DropVertex",     "g.V('thomas').drop()" },
    };
    
  • Utwórz obiekt połączenia GremlinServer przy użyciu parametrów podanych powyżej (wiersz 52):Create a GremlinServer connection object using the parameters provided above (Line 52):

    var gremlinServer = new GremlinServer(hostname, port, enableSsl: true, 
                                                    username: "/dbs/" + database + "/colls/" + collection, 
                                                    password: authKey);
    
  • Utwórz nowy obiekt GremlinClient (wiersz 56):Create a new GremlinClient object (Line 56):

    var gremlinClient = new GremlinClient(gremlinServer, new GraphSON2Reader(), new GraphSON2Writer(), GremlinClient.GraphSON2MimeType);
    
  • Wykonaj wszystkie zapytania języka Gremlin za pomocą obiektu GremlinClient przy użyciu zadania asynchronicznego (wiersz 63).Execute each Gremlin query using the GremlinClient object with an async task (Line 63). Spowoduje to odczytanie zapytań języka Gremlin ze słownika zdefiniowanego powyżej (wiersz 26):This will read the Gremlin queries from the dictionary defined above (Line 26):

    var results = await gremlinClient.SubmitAsync<dynamic>(query.Value);
    
  • Pobierz wynik i odczytaj wartości sformatowane jako słownik przy użyciu klasy JsonSerializer z pakietu Newtonsoft.Json:Retrieve the result and read the values, which are formatted as a dictionary, using the JsonSerializer class from Newtonsoft.Json:

    foreach (var result in results)
    {
        // The vertex results are formed as dictionaries with a nested dictionary for their properties
        string output = JsonConvert.SerializeObject(result);
        Console.WriteLine(String.Format("\tResult:\n\t{0}", output));
    }
    

Aktualizowanie parametrów połączeniaUpdate your connection string

Teraz wróć do witryny Azure Portal, aby uzyskać informacje o parametrach połączenia i skopiować je do aplikacji.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. W witrynie Azure Portal przejdź do swojego konta bazy danych programu Graph.From the Azure portal, navigate to your graph database account. Na karcie Przegląd są wyświetlane dwa punkty końcowe:In the Overview tab, you can see two endpoints-

    Identyfikator URI zestawu .NET SDK — ta wartość jest używana podczas łączenia się z kontem grafu przy użyciu biblioteki Microsoft. Azure. graphs..NET SDK URI - This value is used when you connect to the graph account by using Microsoft.Azure.Graphs library.

    Punkt końcowy języka Gremlin — ta wartość jest używana podczas nawiązywania połączenia z kontem programu Graph przy użyciu biblioteki Gremlin.Net.Gremlin Endpoint - This value is used when you connect to the graph account by using Gremlin.Net library.

    Kopiowanie punktu końcowego

    Aby uruchomić ten przykład, skopiuj wartość punktu końcowego języka Gremlin, usuń numer portu na końcu, otrzymując identyfikator URI https://<your cosmos db account name>.gremlin.cosmosdb.azure.comTo run this sample, copy the Gremlin Endpoint value, delete the port number at the end, that is the URI becomes https://<your cosmos db account name>.gremlin.cosmosdb.azure.com

  2. W pliku Program.cs wklej wartość w miejsce ciągu your-endpoint dla zmiennej hostname w wierszu 19.In Program.cs paste the value over your-endpoint in the hostname variable in line 19.

    "private static string hostname = "<your cosmos db account name>.gremlin.cosmosdb.azure.com";

    Wartość punktu końcowego powinna wyglądać następująco:The endpoint value should now look like this:

    "private static string hostname = "testgraphacct.gremlin.cosmosdb.azure.com";

  3. Następnie przejdź na kartę Klucze i skopiuj wartość KLUCZ PODSTAWOWY z portalu, a następnie wklej ją w zmiennej authkey, zastępując symbol zastępczy "your-authentication-key" w wierszu 21.Next, navigate to the Keys tab and copy PRIMARY KEY value from the portal, and paste it in the authkey variable, replacing the "your-authentication-key" placeholder in line 21.

    private static string authKey = "your-authentication-key";

  4. Korzystając z informacji o bazie danych utworzonej powyżej, wklej nazwę bazy danych wewnątrz zmiennej database w wierszu 22.Using the information of the database created above, paste the database name inside of the database variable in line 22.

    private static string database = "your-database";

  5. Podobnie, korzystając z informacji o utworzonym powyżej kontenerze, wklej nazwę kolekcji (która jest też nazwą grafu) wewnątrz zmiennej collection w wierszu 23.Similarly, using the information of the container created above, paste the collection (which is also the graph name) inside of the collection variable in line 23.

    private static string collection = "your-collection-or-graph";

  6. Zapisz plik Program.cs.Save the Program.cs file.

Aplikacja została zaktualizowana i zawiera teraz wszystkie informacje potrzebne do nawiązania komunikacji z usługą Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Uruchamianie aplikacji konsolowejRun the console app

Naciśnij klawisze CTRL + F5, aby uruchomić aplikację.Click CTRL + F5 to run the application. Aplikacja będzie wyświetlać polecenia zapytań języka Gremlin i ich wyniki w konsoli.The application will print both the Gremlin query commands and results in the console.

W oknie konsoli będą widoczne wierzchołki i krawędzie dodawane do grafu.The console window displays the vertexes and edges being added to the graph. Po zakończeniu działania skryptu naciśnij klawisz ENTER dwa razy, aby zamknąć okno konsoli.When the script completes, press ENTER to close the console window.

Przeglądanie za pomocą Eksploratora danychBrowse using the Data Explorer

Teraz możesz wrócić do Eksploratora danych w witrynie Azure Portal, aby przeglądać nowe dane i wykonywać zapytania względem nich.You can now go back to Data Explorer in the Azure portal and browse and query your new graph data.

  1. W Eksploratorze danych nowa baza danych jest wyświetlana w okienku Grafy.In Data Explorer, the new database appears in the Graphs pane. Rozwiń węzły bazy danych i kontenera, a następnie kliknij pozycję Graf.Expand the database and container nodes, and then click Graph.

  2. Kliknij polecenie Zastosuj filtr, aby użyć domyślnego zapytania do wyświetlenia wszystkich wierzchołków grafu.Click the Apply Filter button to use the default query to view all the vertices in the graph. Dane wygenerowane przez przykładową aplikację zostaną wyświetlone w okienku Grafy.The data generated by the sample app is displayed in the Graphs pane.

    Możesz powiększać i zmniejszać graf, rozszerzać obszar wyświetlania grafu, dodawać kolejne wierzchołki oraz przenosić wierzchołki na wyświetlanej powierzchni.You can zoom in and out of the graph, you can expand the graph display space, add additional vertices, and move vertices on the display surface.

    Wyświetlanie grafu w Eksploratorze danych w witrynie Azure Portal

Przeglądanie umów SLA w witrynie Azure PortalReview SLAs in the Azure portal

Azure Portal monitoruje przepływność, magazyn, dostępność, opóźnienia i spójność konta Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Wykresy dla metryk skojarzonych z Umowa dotycząca poziomu usług Azure Cosmos dB (SLA) pokazują wartość SLA w porównaniu z rzeczywistą wydajnością.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Ten pakiet metryk pozwala monitorować umowy SLA przezroczyste.This suite of metrics makes monitoring your SLAs transparent.

Aby przejrzeć metryki i umowy SLA:To review metrics and SLAs:

  1. Wybierz pozycję metryki w menu nawigacji konta Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Wybierz kartę, na przykład opóźnienie, a następnie wybierz przedział czasu po prawej stronie.Select a tab such as Latency, and select a timeframe on the right. Porównaj wiersze rzeczywiste i SLA na wykresach.Compare the Actual and SLA lines on the charts.

    Zestaw metryk w usłudze Azure Cosmos DB

  3. Przejrzyj metryki na innych kartach.Review the metrics on the other tabs.

Oczyszczanie zasobówClean up resources

Gdy skończysz korzystanie z aplikacji sieci Web i konta Azure Cosmos DB, możesz usunąć utworzone zasoby platformy Azure, aby nie nawiązać dodatkowych opłat.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Aby usunąć zasoby:To delete the resources:

  1. W witrynie Azure Portal na końcu z lewej strony wybierz pozycję Grupy zasobów.In the Azure portal, select Resource groups on the far left. Jeśli menu po lewej stronie jest zwinięte, wybierz przycisk rozwiń, aby je rozwinąć.If the left menu is collapsed, select Expand button to expand it.

  2. Wybierz grupę zasobów utworzoną dla tego przewodnika Szybki Start.Select the resource group you created for this quickstart.

    Wybierz grupę zasobów do usunięcia

  3. W nowym oknie wybierz pozycję Usuń grupę zasobów.In the new window, select Delete resource group.

    Usuwanie grupy zasobów

  4. W następnym oknie wprowadź nazwę grupy zasobów do usunięcia, a następnie wybierz pozycję Usuń.In the next window, enter the name of the resource group to delete, and then select Delete.

Następne krokiNext steps

W tym przewodniku Szybki start wyjaśniono sposób tworzenia konta usługi Azure Cosmos DB, tworzenia grafu za pomocą Eksploratora danych i uruchamiania aplikacji.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a graph using the Data Explorer, and run an app. Teraz możesz tworzyć bardziej złożone zapytania i implementować zaawansowaną logikę przechodzenia grafu za pomocą języka Gremlin.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.