Registrace a používání vlastních konektorů v PowerAppsRegister and use custom connectors in PowerApps

PowerApps vám umožňují vytvářet plnohodnotné aplikace bez tradičního kódu pro aplikace.PowerApps enables you to build full-featured apps with no traditional application code. V některých případech ale potřebujete možnosti PowerApps rozšířit a přirozeně se k tomu hodí webové služby.But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. Aplikace se může ke službě připojit, provést operace a získat zpět data.Your app can connect to a service, perform operations, and get data back. Když máte webovou službu, ke které se chcete pomocí PowerApps připojit, službu zaregistrujete jako vlastní konektor.When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. Tento proces umožní, aby PowerApps pochopily charakteristiku vašeho webového rozhraní API, včetně vyžadovaného ověřování, operací, které podporuje, a parametrů a výstupů pro každou z těchto operací.This process enables PowerApps to understand the characteristics of your web API, including the authentication that it requires, the operations that it supports, and the parameters and outputs for each of those operations.

V tomto tématu se podíváme na kroky potřebné k registraci a používání vlastního konektoru a jako příklad využijeme Rozhraní API pro analýzu textu pro Azure Cognitive Services.In this topic, we'll look at the steps required to register and use a custom connector, and we'll use the Azure Cognitive Services Text Analytics API as an example. Toto rozhraní API identifikuje jazyk, ladění a klíčové fráze v textu, který mu předáte.This API identifies the language, sentiment, and key phrases in text that you pass to it. Následující obrázek ukazuje interakci mezi službou, vlastním konektorem, který z něho vytvoříme, a aplikací, která volá rozhraní API.The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

Rozhraní API, vlastní konektor a aplikace

PožadavkyPrerequisites

  • Účet PowerAppsA PowerApps account.
  • Soubor OpenAPI ve formátu JSON, adresa URL k definici OpenAPI nebo Postman Collection pro vaše rozhraní API.An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. Pokud nic z toho nemáte, poradíme vám s postupem.If you don't have any of these, we'll provide guidance for you.
  • Obrázek, který chcete použít jako ikonu vlastního konektoru (volitelné)An image to use as an icon for your custom connector (optional).

Kroky v procesu vlastního konektoruSteps in the custom connector process

Proces vlastního konektoru má několik kroků, které stručně popisujeme níže.The custom connector process has several steps, which we describe briefly below. Tento článek předpokládá, že už máte rozhraní RESTful API s některým typem ověřeného přístupu, proto se ve zbytku článku zaměříme na kroky 3 až 6.This article assumes you already have a RESTful API with some type of authenticated access, so we'll focus on steps 3-6 in the rest of the article. Příklady kroků 1 a 2 najdete v článku o vytvoření vlastního rozhraní Web API pro PowerApps.For an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. Sestavte rozhraní RESTful API v jazyce a na platformě podle svého výběru.Build a RESTful API in the language and platform of your choice. Pro technologie Microsoft doporučujeme jednu z těchto možností:For Microsoft technologies, we recommend one of the following.

    • Funkce AzureAzure Functions
    • Azure Web AppsAzure Web Apps
    • Azure API AppsAzure API Apps
  2. Zabezpečte své rozhraní API pomocí některého z následujících mechanismů ověřování.Secure your API using one of the following authentication mechanisms. Můžete povolit neověřený přístup k rozhraním API, ale to nedoporučujeme.You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. Popište své rozhraní API jedním ze dvou standardních způsobů, aby se k němu mohly PowerApps připojit.Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • Soubor OpenAPI (nazývaný také jako soubor Swagger)An OpenAPI file (also known as a Swagger file)
    • Postman CollectionA Postman Collection

      Soubor OpenAPI můžete také sestavit ve 4. kroku procesu registrace.You can also build an OpenAPI file in step 4 as part of the registration process.

  4. Zaregistrujte svůj vlastní konektor pomocí průvodce v PowerApps, kde můžete zadat popis rozhraní API, podrobnosti o zabezpečení a další informace.Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. Použijte vlastní konektor v aplikaci.Use your custom connector in an app. Vytvořte připojení k rozhraní API ve vaší aplikaci a volejte jakékoli operace, které rozhraní API poskytuje, stejně jako voláte nativní funkce v PowerApps.Create a connection to the API in your app, and call any operations that the API provides, just like you call native functions in PowerApps.
  6. Sdílejte vlastní konektor stejně jako jiná datová připojení v PowerApps.Share your custom connector like you do other data connections in PowerApps. Tento krok je volitelný, ale často má smysl vlastní konektory sdílet mezi více tvůrci aplikací.This step is optional, but it often makes sense to share custom connectors across multiple app creators.

Popis rozhraní APIDescribe your API

Za předpokladu, že máte rozhraní API s nějakým typem ověřeného přístupu, potřebujete způsob, jak rozhraní API popsat, aby se k němu mohly PowerApps připojit.Assuming you have an API with some type of authenticated access, you need a way to describe the API so that PowerApps can connect to it. K tomuto účelu vytvoříte soubor OpenAPI nebo Postman Collection. To můžete udělat z libovolného koncového bodu REST API, včetně těchto:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • Veřejně dostupná rozhraní API.Publicly available APIs. Mezi příklady patří Spotify, Uber, Slack, Rackspace a další.Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • Rozhraní API, které vytvoříte a nasadíte pro libovolného poskytovatele cloudového hostingu, včetně Azure, Amazon Web Services (AWS), Heroku, Google Cloud a dalšíchAn API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • Vlastní obchodní rozhraní API nasazené ve vaší síti, pokud je vystavené na veřejném internetuA custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

Soubory OpenAPI a Postman Collection používají různé formáty, ale oba jsou strojově čitelnými dokumenty bez rozlišení jazyka, které popisují operace a parametry vašeho rozhraní API:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • Tyto dokumenty můžete generovat pomocí různých nástrojů v závislosti na jazyku a platformě, na kterých je vaše rozhraní API založené.You can generate these documents using a variety of tools depending on the language and platform that your API is built on. Příklad souboru Open API najdete v dokumentaci k rozhraní API pro analýzu textu.See the Text Analytics API documentation for an example of an OpenAPI file.
  • Pokud ještě soubor OpenAPI pro svoje rozhraní API nemáte a nechcete ho vytvářet, můžete vlastní konektor i tak snadno vytvořit pomocí Postman Collection.If you don't already have an OpenAPI file for your API and don't want to create one, you can still easily create a custom connector by using a Postman Collection. Další informace najdete v článku o vytvoření Postman Collection.See Create a Postman Collection for more information.
  • PowerApps používají OpenAPI v podstatě na pozadí, takže se Postman Collection analyzuje a převede na soubor definice OpenAPI.PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

Poznámka:: Váš soubor musí být menší než 1 MB.Note: Your file size must be less than 1MB.

Začínáme s OpenAPI a PostmanemGetting started with OpenAPI and Postman

Zaregistrování vlastního konektoruRegister your custom connector

Teď soubor OpenAPI nebo Postman Collection použijete k zaregistrování vlastního konektoru v PowerApps.You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. V levé nabídce na webu powerapps.com vyberte Připojení.In powerapps.com, in the left menu, select Connections. Vyberte tři tečky (...) a pak vpravo nahoře vyberte Spravovat vlastní konektory.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Tip: Pokud v mobilním prohlížeči nemůžete najít, kde se vlastní konektory spravují, vyzkoušejte nabídku vlevo nahoře.Tip: If you can't find where to manage custom connectors in a mobile browser, it might be under a menu in the upper left corner.

    Vytvoření vlastního konektoru

  2. Zvolte Vytvořit vlastní konektor.Select Create custom connector.

    Vlastnosti vlastního konektoru

  3. Na kartě Obecné zvolte, jak chcete vlastní konektor vytvořit.In the General tab, choose how you want to create the custom connector.

    • Odeslat soubor OpenAPIUpload an OpenAPI file
    • Použijte adresu URL OpenAPIUse an OpenAPI URL
    • Nahrát Postman Collection V1Upload Postman Collection V1

      Jak vytvořit vlastní konektor

      Nahrajte ikonu pro vlastní konektor.Upload an icon for your custom connector. Pole Popis, Hostitel a Základní adresa URL jsou obvykle automaticky vyplněná informacemi ze souboru OpenAPI.Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. Pokud automaticky vyplněná nejsou, můžete do nich informace přidat.If they are not auto-populated, you can add information to those fields. Vyberte Pokračovat.Select Continue.

  4. Na kartě Zabezpečení zadejte všechny vlastnosti ověřování.In the Security tab, enter any authentication properties.

    Typy ověřování

    • Typ ověřování se automaticky vyplnění podle toho, co je definované ve vašem objektu OpenAPI securityDefinitions.The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. Níže je příklad OAuth2.0.Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • Pokud soubor OpenAPI objekt securityDefintions nepoužívá, pak žádné další hodnoty nejsou potřeba.If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • Pokud používáte Postman Collection, typ ověřování se automaticky vyplní jenom při použití podporovaných typů ověřování jako OAuth 2.0 a Základní.When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Příklad nastavení ověřování Azure Active Directory (AAD) najdete v části o vytvoření vlastního rozhraní Web API pro PowerApps.For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for PowerApps.
  5. Na kartě Definice se automaticky vyplní všechny operace, které jsou definované v souboru OpenAPI nebo Postman Collection, společně s hodnotami požadavků a odpovědí.In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. Pokud jsou definované všechny vaše požadované operace, můžete přejít ke kroku 6 v procesu registrace bez provedení změn na této obrazovce.If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    Karta Definice

    Pokud chcete upravit existující akce nebo do vlastního konektoru přidat nové akce, pokračujte ve čtení.If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. Pokud chcete přidat novou akci, která ještě ve vašem souboru OpenAPI nebo Postman Collection není, vyberte v levém podokně Nová akce a v sekci Obecné vyplňte název, popis a viditelnost operace.If you want to add a new action that was not already in your OpenAPI file or Postman Collection, select New action in the left pane and fill in the General section with the name, description, and visibility of your operation.
    2. V části Požadavek vyberte vpravo nahoře Importovat z ukázky.In the Request section, select Import from sample on the top right. Do formuláři na pravé straně vložte ukázkový požadavek.In the form on the right, paste in a sample request. Ukázkové požadavky jsou obvykle dostupné v dokumentaci rozhraní API, kde můžete získat informace k vyplnění polí Příkaz, URL žádosti, Záhlaví a Text.Sample requests are usually available in the API documentation, where you can get information to fill out the Verb, Request URL, Headers, and Body fields. Příklad najdete v dokumentaci k rozhraní API pro analýzu textu.See the Text Analytics API documentation for an example.

      Importování z ukázky

    3. K dokončení definice požadavku vyberte Importovat.Select Import to complete the request definition. Podobně definujte odpověď.Define the response in a similar way.
  6. Až budete mít všechny operace definované, pomocí Vytvořit vytvořte vlastní konektor.Once you have all your operations defined, select Create to create your custom connector.
  7. Po vytvoření vlastního konektoru přejděte na kartu Test a otestujte operace definované v rozhraní API.Once you have created your custom connector, go to the Test tab to test the operations defined in the API. Vyberte připojení a zadejte vstupní parametry k otestování operace.Choose a connection, and provide input parameters to test an operation.

    Otestování vlastního konektoru

    Pokud je volání úspěšné, získáte platnou odpověď.If the call is successful, you get a valid response.

    Odpověď testu rozhraní API

Používání vlastního konektoruUse your custom connector

Když teď máte rozhraní API zaregistrované, přidejte vlastní konektor do aplikace stejně, jako byste přidali jakýkoli jiný zdroj dat.Now that you've registered your API, add the custom connector to your app like you would any other data source. Ukážeme si to tady na stručném příkladu.We'll go through a brief example here. Další informace o datových připojeních najdete v tématu Přidání datového připojení v PowerApps.For more information about data connections, see Add a data connection in PowerApps.

  1. V pravém podokně v PowerApps Studiu klikněte nebo klepněte na Přidat zdroj dat.In PowerApps Studio, in the right pane, click or tap Add data source.

  2. Klikněte nebo klepněte na vlastní konektor, který jste vytvořili.Click or tap the custom connector that you created.

  3. Proveďte všechny kroky nezbytné pro přihlášení ke službě, ke které se připojujete.Complete any steps necessary to sign in to the service you're connecting to. Pokud vaše rozhraní API používá ověřování OAuth, může se vám zobrazit přihlašovací obrazovka.If your API uses OAuth authentication, you might be presented a sign-in screen. Při ověřování klíče rozhraní API se může zobrazit výzva k zadání hodnoty klíče.For API key authentication, you might be prompted for a key value.
  4. Zavolejte rozhraní API ve vaší aplikaci.Call the API in your app. Pro náš příklad jsme vytvořili aplikaci, která odešle text do Cognitive Services a získá zpět skóre mínění 0 až 1, které aplikace zobrazí v procentech.For our example, we created an app that submits text to Cognitive Services and gets back a sentiment score of 0 to 1, which the app shows as a percentage.

    • Když s tímto konektorem začnete do řádku vzorců psát „Az“, zobrazí se rozhraní API a operace, které jsou díky němu dostupné.With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • Takto vypadá kompletní volání, kde předáváme text z ovládacího prvku TextInput, a zpět získáváme skóre k zobrazení v aplikaci:The complete call looks like this, where we pass in text from the TextInput control and get back a score to display in the app:

      'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
      
    • V aplikaci ještě provedeme pár dalších kroků kvůli zpracování dat, která se do ní vracejí, ale není to nic složitého.We do a little more work in the app to handle the data that comes back, but it's not too complicated.

Dokončená aplikace vypadá jako na následujícím obrázku.The finished app looks like the following image. Je to jednoduchá aplikace, která ale získává účinnou funkci díky tomu, že prostřednictvím vlastního konektoru dokáže volat Cognitive Services.It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

Kvóty a omezováníQuota and throttling

  • Podrobnosti o kvótách pro vytváření vlastních konektorů najdete na stránce s cenami PowerApps.See the PowerApps Pricing page for details about custom connector creation quotas. Vlastní konektory, které s vámi někdo sdílí, se do této kvóty nezapočítávají.Custom connectors that are shared with you don't count against this quota.
  • Pro každé připojení vytvořené ve vlastním konektoru můžou uživatelé provést až 500 požadavků za minutu.For each connection created on a custom connector, users can make up to 500 requests per minute.

Sdílení vlastního konektoruShare your custom connector

Když teď máte vlastní konektor, můžete ho sdílet s ostatními uživateli ve vaší organizaci.Now that you have a custom connector, you can share it with other users in your organization. Nezapomínejte, že když sdílíte rozhraní API, můžou na něm ostatní začít záviset a odstraněním vlastního konektoru se odstraní všechna připojení k rozhraní API.Keep in mind that when you share an API, others might start to depend on it, and deleting a custom connector deletes all the connections to the API. Pokud chcete poskytnout konektor pro uživatele mimo vaši organizaci, přečtěte si přehled o certifikaci vlastních konektorů v PowerApps.If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. V levé nabídce na webu powerapps.com vyberte Připojení.In powerapps.com, in the left menu, select Connections. Vyberte tři tečky (...) a pak vpravo nahoře vyberte Spravovat vlastní konektory.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Nové připojení

  2. Vyberte tlačítko se třemi tečkami (... ) u vašeho konektoru a pak vyberte Zobrazit vlastnosti.Select the ellipsis (. . .) button for your connector, then select View properties.

    Zobrazení vlastností konektoru

  3. Vyberte vaše rozhraní API, vyberte Sdílet a pak zadejte uživatele nebo skupiny, kterým chcete udělit přístup k vašemu rozhraní API.Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    Sdílení vlastního konektoru

  4. Vyberte Uložit.Select Save.

Další krokyNext steps

Zjistěte, jak vytvořit Postman CollectionLearn how to create a Postman Collection

Používání rozhraní Web API ASP.NETUse an ASP.NET Web API.

Registrace rozhraní API Azure Resource ManageruRegister an Azure Resource Manager API.