Egyéni összekötők regisztrálása és használata a PowerAppsbenRegister and use custom connectors in PowerApps

A PowerApps teljes körű alkalmazások létrehozását teszi lehetővé hagyományos programkód írása nélkül.PowerApps enables you to build full-featured apps with no traditional application code. De egyes esetekben szükség lehet a PowerApps képességeinek kiterjesztésére, és a webszolgáltatások természetesen alkalmasak erre a célra.But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. Az alkalmazás képes kapcsolódni egy szolgáltatáshoz, különböző műveleteket végezni, és adatokat visszakérni.Your app can connect to a service, perform operations, and get data back. Ha van egy webszolgáltatás-bővítménye, amelyhez csatlakoztatni kívánja a PowerApps-t, regisztrálja a szolgáltatást egyéni összekötőként.When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. Ez a folyamat lehetővé teszi, hogy a PowerApps ismerje a webes API jellemzőit, beleértve a szükséges hitelesítést, a támogatott műveleteket, és az általa szolgáltatott paramétereket és kimeneteket az egyes műveletek esetén.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.

Ebben a témakörben áttekintjük az egyéni összekötő regisztrálásához és használatához szükséges lépéseket, és az Azure Cognitive Services Szövegelemzési API-t fogjuk használni példaként.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. Ez az API felismeri a neki átadott szöveg nyelvét, hangnemét és kulcskifejezéseit.This API identifies the language, sentiment, and key phrases in text that you pass to it. A következő kép bemutatja a szolgáltatást, az egyéni összekötőt, amit belőle létrehozunk, és az API-t hívó alkalmazást.The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

API, egyéni összekötő és alkalmazás

ElőfeltételekPrerequisites

  • PowerApps-fiók.A PowerApps account.
  • Egy JSON formátumú OpenAPI-fájl, egy OpenAPI-definíció URL-címe vagy egy, az API-hoz tartozó Postman-gyűjtemény.An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. Ha ezek egyikével sem rendelkezik, iránymutatással szolgálunk Önnek.If you don't have any of these, we'll provide guidance for you.
  • Az egyéni (nem kötelező) összekötő ikonjaként használandó kép.An image to use as an icon for your custom connector (optional).

Az egyéni összekötő folyamat lépéseiSteps in the custom connector process

Az egyéni összekötő folyamat számos lépést tartalmaz, amelyeket alább röviden ismertetünk.The custom connector process has several steps, which we describe briefly below. Ez a cikk azt feltételezi a RESTful API-t, bizonyos típusú már hitelesített hozzáféréssel, ezért a cikk további részében a 3–6. lépésre összpontosítunk.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. Az 1. és 2. lépéshez példáért lásd: Egyéni Web API létrehozása a PowerApps-hoz.For an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. Készítsen RESTful API-t az Ön által választott nyelvhez és platformhoz.Build a RESTful API in the language and platform of your choice. A Microsoft-technológiák közül a következők valamelyike ajánlott.For Microsoft technologies, we recommend one of the following.

    • Azure FunctionsAzure Functions
    • Azure Web AppsAzure Web Apps
    • Azure API AppsAzure API Apps
  2. Az API védelme az alábbi hitelesítési módszerek egyikének használatával.Secure your API using one of the following authentication mechanisms. Az API-hoz nem hitelesített hozzáférést is biztosíthat, de nem ajánlott.You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. Az API leírása két szabványos módszer valamelyikével, hogy a PowerApps csatlakozni tudjon hozzá.Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • Egy OpenAPI-fájl (más néven Swagger-fájl)An OpenAPI file (also known as a Swagger file)
    • Egy Postman-gyűjteményA Postman Collection

      A 4. lépésben a regisztrációs folyamat részeként OpenAPI-fájl is létrehozható.You can also build an OpenAPI file in step 4 as part of the registration process.

  4. Az egyéni összekötő regisztrálása varázsló segítségével a PowerApps-ban, ahol meg kell határoznia az API leírását, biztonsági részleteit és más információkat.Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. Az egyéni összekötő használata egy alkalmazásban.Use your custom connector in an app. Hozza létre az API-kapcsolatot az alkalmazásban, és bármely, az API által biztosított műveletet hívhat, akárcsak a natív PowerApps-függvényeket.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. Az egyéni összekötő megosztása ugyanúgy történhet, mint amikor más adatkapcsolatokat oszt meg a PowerApps segítségével.Share your custom connector like you do other data connections in PowerApps. Ez a lépés nem kötelező, de gyakran érdemes az egyéni összekötők megosztása több alkalmazáskészítő között.This step is optional, but it often makes sense to share custom connectors across multiple app creators.

Az API leírásának megadásaDescribe your API

Ha rendelkezik egy, valamilyen típusú hitelesített hozzáféréssel rendelkező API-val, le kell írnia az API-t, hogy a PowerApps segítségével tudjon hozzá csatlakozni.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. Ehhez az szükséges egy OpenAPI-fájl vagy Postman gyűjtemény létrehozása – amely megtehető bármely REST API-végpontról, beleértve a következőket:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • Nyilvánosan elérhető API-k.Publicly available APIs. Ilyenek például a következők: Spotify, Uber, Slack, Rackspace stb.Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • Egy felhőalapú szolgáltatón, például Azure, Amazon Web Services (AWS), Heroku, Google Cloud stb. létrehozott és üzembe helyezett API.An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • Egy, a hálózaton telepített egyéni üzleti API, feltéve, hogy az API-t elérhetővé tették a nyilvános interneten.A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

Az OpenAPI-fájlok és Postman-gyűjtemények különböző formátumot használnak, de mindkettő nyelvtől független, géppel olvasható dokumentum, amely ismerteti az API-műveleteket és paramétereket:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • Ezeket a dokumentumokat számos különféle eszközzel létrehozhatja azon nyelvtől és platformtól függően, amelyre az AP épül.You can generate these documents using a variety of tools depending on the language and platform that your API is built on. A Szövegelemzési API dokumentációjában láthat egy példa OpenAPI-fájlt.See the Text Analytics API documentation for an example of an OpenAPI file.
  • Ha nem rendelkezik egy OpenAPI-fájllal az API-hoz, és nem szeretne létrehozni egyet, továbbra is könnyedén létrehozhat egy egyéni összekötőt Postman-gyűjtemény használatával.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. További információért lásd a Postman gyűjtemény létrehozása című témakört.See Create a Postman Collection for more information.
  • A PowerApps végső soron OpenAPI-t használ a háttérben, így a Postman-gyűjtemények elemzés után egy OpenAPI-definíciós fájlra lesznek lefordítva.PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

Megjegyzés:: A fájlméret csak 1 MB-nál kevesebb lehet.Note: Your file size must be less than 1MB.

Ismerkedés az OpenAPI-val és a PostmannelGetting started with OpenAPI and Postman

Az egyéni összekötő regisztrálásaRegister your custom connector

Most az OpenAPI-fájl vagy a Postman-gyűjtemény használatával fogja regisztrálni az egyéni összekötőt a PowerApps-ban.You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. A powerapps.com oldal bal oldali menüjében válassza a Kapcsolatok lehetőséget.In powerapps.com, in the left menu, select Connections. Kattintson a három pontra (...), majd válassza az Egyéni összekötők kezelése lehetőséget a jobb felső sarokban.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Tipp: Ha nem találja a mobilböngészőben az egyéni összekötők kezelési helyét, lehetséges, hogy a bal felső sarokban található menüben kell keresnie.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.

    Egyéni összekötő létrehozása

  2. Válassza az Egyéni összekötő létrehozása lehetőséget.Select Create custom connector.

    Egyéni összekötő tulajdonságai

  3. Az Általános lapon válassza ki, hogyan szeretné létrehozni az egyéni összekötőt.In the General tab, choose how you want to create the custom connector.

    • OpenAPI-fájl feltöltéseUpload an OpenAPI file
    • OpenAPI-alapú URL-cím használataUse an OpenAPI URL
    • Postman Collection V1 feltöltéseUpload Postman Collection V1

      Egy egyéni összekötő létrehozása

      Töltse fel az egyéni összekötő ikonját.Upload an icon for your custom connector. A Leírás, az Állomás és az Alap URL-cím mező kitöltése általában automatikusan történik az OpenAPI-fájl adataival.Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. Ha nincsenek automatikusan kitöltve, hozzáadhat adatokat ezekhez a mezőkhöz.If they are not auto-populated, you can add information to those fields. Válassza a Folytatás lehetőséget.Select Continue.

  4. A Biztonság lapon adja meg a kívánt hitelesítési tulajdonságokat.In the Security tab, enter any authentication properties.

    Hitelesítési típusok

    • A hitelesítési típust automatikusan kitölti a rendszer az OpenAPI securityDefinitions objektumában szereplő definíciók alapján.The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. Az alábbiakban egy OAuth2.0-s példa látható.Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • Ha az OpenAPI-fájl nem használja a securityDefintions objektumot, akkor nincs szükség további érték megadására.If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • Postman-gyűjtemény használatakor a hitelesítési típus automatikus kitöltése csak támogatott hitelesítési típus, például az OAuth 2.0-s vagy az Alapszintű hitelesítés használata esetén támogatott.When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Egy Azure Active Directory (AAD) hitelesítés beállítására vonatkozó példáért tekintse meg az Egyéni Web API létrehozása a PowerApps-hoz című részt.For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for PowerApps.
  5. A Definíciók lapon az OpenAPI-fájl vagy a Postman-gyűjtemény által meghatározott műveletek automatikusan ki vannak töltve a kérelem-válasz értékekkel együtt.In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. Ha a szükséges műveletek meg vannak határozva, folytathatja a regisztrációs folyamat 6. lépésével ezen a képernyőn végzett módosítások nélkül.If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    Definíció lap

    Ha szeretné szerkeszteni a meglévő műveleteket, vagy új műveleteket felvenni az egyéni összekötőbe, olvasson tovább.If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. Ha hozzá szeretne adni egy új műveletet, amely még nem szerepel az Ön OpenAPI-fájljában vagy a Postman-gyűjteményben, válassza az Új művelet elemet a bal oldali ablaktáblán, és adja meg az Általános szakaszban a művelet nevét, leírását és láthatóságát.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. A Kérelem szakaszban válassza a jobb felső sarokban lévő Importálás mintából lehetőséget.In the Request section, select Import from sample on the top right. A jobb oldali űrlapon illesszen be egy mintakérelmet.In the form on the right, paste in a sample request. Mintakérelmek általában az API dokumentációjában érhetők el, ahol segítséget talál a Művelet, Kérelem URL-címe, Fejlécek és Törzs mezők kitöltéséhez.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. A Szövegelemzési API dokumentációjában láthat egy példát.See the Text Analytics API documentation for an example.

      Importálás mintából

    3. Válassza az Importálás lehetőséget a kérelem definíciójának befejezéséhez.Select Import to complete the request definition. Hasonló módon adja meg a választ.Define the response in a similar way.
  6. Miután definiálta az összes műveletet, válassza a Létrehozás lehetőséget az egyéni összekötő létrehozásához.Once you have all your operations defined, select Create to create your custom connector.
  7. Miután létrehozta a egyéni összekötőt, navigáljon a Tesztelés lapra, ahol tesztelheti az API-ban megadott műveleteket.Once you have created your custom connector, go to the Test tab to test the operations defined in the API. Válassza ki a kapcsolatot, és adjon meg bemeneti paramétereket egy művelet teszteléséhez.Choose a connection, and provide input parameters to test an operation.

    Egyéni összekötő tesztelése

    Ha a hívás sikeres, érvényes választ kap.If the call is successful, you get a valid response.

    API-válaszidő tesztelése

Az egyéni összekötő használataUse your custom connector

Most, hogy az API-t regisztrálta, adja hozzá az egyéni összekötőt az alkalmazáshoz, mint bármely más adatforrást.Now that you've registered your API, add the custom connector to your app like you would any other data source. A következő rövid példa végighalad ennek lépésein.We'll go through a brief example here. Az adatkapcsolatokkal kapcsolatos további információkért lásd: Adatkapcsolat hozzáadása a PowerAppsben.For more information about data connections, see Add a data connection in PowerApps.

  1. A PowerApps Studióban a jobb oldali ablaktáblán kattintson vagy koppintson az Adatforrás hozzáadása lehetőségre.In PowerApps Studio, in the right pane, click or tap Add data source.

  2. Kattintson vagy koppintson a létrehozott egyéni összekötőre.Click or tap the custom connector that you created.

  3. Végezzen el minden szükséges lépést azon szolgáltatásba való bejelentkezéshez, amelyhez kapcsolódik.Complete any steps necessary to sign in to the service you're connecting to. Ha az API OAuth-hitelesítést használ, akkor előfordulhat, hogy megjelenik egy bejelentkezési képernyő.If your API uses OAuth authentication, you might be presented a sign-in screen. API-kulcs alapú hitelesítés esetén a rendszer bekérheti a kulcs értékét.For API key authentication, you might be prompted for a key value.
  4. Az API hívása az alkalmazásban.Call the API in your app. A fenti példában létrehozott egy alkalmazást, amely elküldi a szöveget a Cognitive Services-hez, és visszakap egy 0 és 1 közé eső véleménypontszámot, amelyet az alkalmazás százalékként jelenít meg.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.

    • Az összekötő esetén, ha elkezdi beírni az „Az” szöveget a szerkesztőlécen, láthatja az API-t és az általa elérhető műveleteket.With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • A teljes hívás a következőképpen néz ki, ahol a TextInput vezérlőből származó szöveget adjuk át, és az alkalmazás megjeleníti a visszakapott pontszámot: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)
      
    • Egy kicsit több munkát végzünk az alkalmazásban, hogy kezeljük az adatokat, de ez nem túl bonyolult.We do a little more work in the app to handle the data that comes back, but it's not too complicated.

A kész alkalmazás a következő képen láthatóhoz hasonló.The finished app looks like the following image. Ez egy egyszerű alkalmazás, de mivel hívni tudja a Cognitive Services-t egy egyéni összekötőn keresztül, hatékony funkciókat tud nyújtani.It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

Kvóta és szabályozásQuota and throttling

  • Az egyéni összekötő létrehozására vonatkozó kvótákkal kapcsolatos részleteket a PowerApps díjszabása lapon tekintheti meg.See the PowerApps Pricing page for details about custom connector creation quotas. Önnel megosztott egyéni összekötők a kvótát nem csökkentik.Custom connectors that are shared with you don't count against this quota.
  • Mindegyik egyéni összekötőn létrehozott kapcsolat esetén a felhasználók legfeljebb 500 kérést hozhatnak létre percenként.For each connection created on a custom connector, users can make up to 500 requests per minute.

Az egyéni összekötő megosztásaShare your custom connector

Most, hogy van egy egyéni összekötőnk, megoszthatjuk azt más felhasználókkal a cégen belül.Now that you have a custom connector, you can share it with other users in your organization. Ne feledje, hogy az API-k megosztásakor mások is függővé válhatnak azoktól, és egy egyéni összekötő törlésével az API-val való minden kapcsolatot töröl.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. Ha szeretne összekötőt biztosítani a cégen kívüli felhasználóknak, tekintse meg A PowerApps egyedi összekötőinek tanúsítása című részt.If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. A powerapps.com oldal bal oldali menüjében válassza a Kapcsolatok lehetőséget.In powerapps.com, in the left menu, select Connections. Kattintson a három pontra (...), majd válassza az Egyéni összekötők kezelése lehetőséget a jobb felső sarokban.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Új kapcsolat

  2. Kattintson az összekötőhöz tartozó három pont (. . .) gombra, és válassza a Tulajdonságok megtekintése lehetőséget.Select the ellipsis (. . .) button for your connector, then select View properties.

    Az összekötő tulajdonságainak megtekintése

  3. Válassza ki az API-t, majd a Megosztás lehetőséget, majd adja meg azon felhasználókat és csoportokat, akiknek hozzáférést szeretne biztosítani az API-hoz.Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    Egyéni összekötő megosztása

  4. Kattintson a Mentés gombra.Select Save.

Következő lépésekNext steps

Postman-gyűjtemény létrehozásának ismertetéseLearn how to create a Postman Collection

ASP.NET webes API használata.Use an ASP.NET Web API.

Azure Resource Manager API regisztrálása.Register an Azure Resource Manager API.