PowerApps'te özel bağlayıcıları kaydetme ve kullanmaRegister and use custom connectors in PowerApps

PowerApps, geleneksel uygulama kodu olmadan tam özellikli uygulamalar oluşturmanıza olanak sağlar.PowerApps enables you to build full-featured apps with no traditional application code. Bazı durumlarda PowerApps özelliklerini genişletmeniz gerekir ve web hizmetleri bunun için biçilmiş kaftandır.But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. Uygulamanız bir hizmete bağlanabilir, işlemler gerçekleştirebilir ve verileri geri alabilir.Your app can connect to a service, perform operations, and get data back. PowerApps ile bağlantılı hale getirmek istediğiniz bir web hizmetiniz olduğunda hizmeti özel bağlayıcı olarak kaydedin.When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. Bu işlemin ardından PowerApps gerekli kimlik doğrulaması, desteklenen işlemler ve bu işlemlerin her birine ilişkin parametreler ve çıkışlar da dahil olmak üzere web API'nizin özelliklerini anlayabilir.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.

Bu konu başlığında, özel bir bağlayıcıyı kaydetmeye ve kullanmaya ilişkin adımları ele alacak ve Azure Bilişsel Hizmetler Metin Analizi API'sini örnek olarak kullanacağız.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. Bu API, kendisine geçirdiğiniz metindeki dili, yaklaşımı ve anahtar ifadeleri tanımlar.This API identifies the language, sentiment, and key phrases in text that you pass to it. Aşağıdaki görüntüde hizmet, hizmetten oluşturduğumuz özel bağlayıcı ve API'yi çağıran uygulama arasındaki etkileşim gösterilmektedir.The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

API, özel bağlayıcı ve uygulama

ÖnkoşullarPrerequisites

  • Bir PowerApps hesabı.A PowerApps account.
  • JSON biçiminde bir OpenAPI dosyası, bir OpenAPI tanımının URL'si veya API'niz için bir Postman Koleksiyonu.An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. Bunlardan herhangi birine sahip değilseniz size yol gösteririz.If you don't have any of these, we'll provide guidance for you.
  • Özel bağlayıcınız için simge olarak kullanılacak bir görüntü (isteğe bağlı).An image to use as an icon for your custom connector (optional).

Özel bağlayıcı işleminin adımlarıSteps in the custom connector process

Özel bağlayıcı işlemi, aşağıda kısaca açıkladığımız birkaç adımı içermektedir.The custom connector process has several steps, which we describe briefly below. Bu makalede, kimliği doğrulanmış erişiminizin bulunduğu bir RESTful API'niz olduğu varsayılmaktadır. Bu nedenle makalenin geri kalan bölümünde 3 ila 6. adımlar ele alınmaktadır.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. 1. ve 2. adıma ilişkin örnek için bkz. PowerApps için özel bir Web API'si oluşturma.For an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. Dilediğiniz dil ve platformda bir RESTful API oluşturun.Build a RESTful API in the language and platform of your choice. Microsoft teknolojileri için aşağıdakilerden birini kullanmanızı öneririz.For Microsoft technologies, we recommend one of the following.

    • Azure İşlevleriAzure Functions
    • Azure Web AppsAzure Web Apps
    • Azure API AppsAzure API Apps
  2. Aşağıdaki kimlik doğrulama yöntemlerinden birini kullanarak API'nizin güvenliğini sağlayın.Secure your API using one of the following authentication mechanisms. API'leriniz için kimliği doğrulanmamış erişime izin verebilirsiniz ancak bunu önermiyoruz.You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. PowerApps'in bağlanabilmesi için, endüstri standardı iki yöntemden birini kullanarak API'nizi açıklayın.Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • Bir OpenAPI dosyası (Swagger dosyası olarak da bilinir)An OpenAPI file (also known as a Swagger file)
    • Bir Postman KoleksiyonuA Postman Collection

      Ayrıca kayıt işleminin bir parçası olarak 4. adımda bir OpenAPI dosyası da oluşturabilirsiniz.You can also build an OpenAPI file in step 4 as part of the registration process.

  4. PowerApps'te; API açıklaması, güvenlik ayrıntıları ve diğer bilgileri belirttiğiniz bir sihirbazı kullanarak özel bağlayıcınızı kaydedin.Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. Bir uygulamada özel bağlayıcınızı kullanın.Use your custom connector in an app. Uygulamanızda API'ye yönelik bir bağlantı oluşturun ve PowerApps'te yerel işlevleri çağırdığınız gibi, API tarafından sağlanan tüm işlemleri çağırın.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. PowerApps'te diğer veri bağlantılarını paylaştığınız gibi özel bağlayıcınızı paylaşın.Share your custom connector like you do other data connections in PowerApps. Bu adım isteğe bağlıdır ancak özel bağlayıcıların birden fazla uygulama oluşturucu ile paylaşılması genellikle mantıklıdır.This step is optional, but it often makes sense to share custom connectors across multiple app creators.

API'nizi açıklamaDescribe your API

Kimliği doğrulanmış erişiminizin bulunduğu bir API'niz olduğu varsayıldığında, PowerApps'in bağlanabilmesi için API'nizi açıklayabileceğiniz bir yönteme ihtiyacınız vardır.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. Bunun için bir OpenAPI dosyası veya bir Postman Koleksiyonu oluşturun. Bunu, aşağıdakiler de dahil olmak üzere herhangi bir REST API uç noktasından yapabilirsiniz:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • Genel kullanıma sunulan API'ler.Publicly available APIs. Spotify, Uber, Slack, Rackspace ve çok daha fazlası örnek olarak gösterilebilir.Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • Oluşturduğunuz ve Azure, Amazon Web Services (AWS), Heroku, Google Cloud gibi herhangi bir bulut barındırma sağlayıcısında dağıttığınız bir API.An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • İnternet'te genel kullanıma sunulması koşuluyla ağınızda dağıtılan özel bir iş kolu API'si.A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

OpenAPI dosyaları ve Postman Koleksiyonları farklı biçimler kullanır ancak her ikisi de API'nizin işlemlerini ve parametrelerini açıklayan, dilden bağımsız, makine tarafından okunabilir belgelerdir:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • API'nizin oluşturulduğu dile ve platforma bağlı olarak bu belgeleri çeşitli araçlarla oluşturabilirsiniz.You can generate these documents using a variety of tools depending on the language and platform that your API is built on. OpenAPI dosyası örneği için bkz. Metin Analizi API'si belgeleri.See the Text Analytics API documentation for an example of an OpenAPI file.
  • API'niz için bir OpenAPI dosyanız yoksa ve oluşturmak istemiyorsanız bir Postman Koleksiyonu kullanarak yine kolayca özel bir bağlayıcı oluşturabilirsiniz.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. Daha fazla bilgi için bkz. Postman Koleksiyonu oluşturma.See Create a Postman Collection for more information.
  • Sonuç olarak PowerApps arka planda OpenAPI'yi kullanır. Böylece Postman Koleksiyonu ayrıştırılır ve bir OpenAPI tanım dosyasına çevrilir.PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

Not: Dosyanızın boyutu 1 MB'tan az olmalıdır.Note: Your file size must be less than 1MB.

OpenAPI ve Postman'ı kullanmaya başlamaGetting started with OpenAPI and Postman

Özel bağlayıcınızı kaydetmeRegister your custom connector

Artık PowerApps'te özel bağlayıcınızı kaydetmek için OpenAPI dosyasını veya Postman Koleksiyonunu kullanacaksınız.You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. powerapps.com adresindeki sol menüde Bağlantılar'ı seçin.In powerapps.com, in the left menu, select Connections. Üç nokta (...) simgesini seçin ve ardından sağ üst köşedeki Özel bağlayıcıları yönet'i seçin.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    İpucu: Bir mobil tarayıcıda özel bağlayıcıların nereden yönetileceğini bulamamanız halinde sol üst köşedeki bir menüye göz atabilirsiniz.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.

    Özel bağlayıcı oluşturma

  2. Özel bağlayıcı oluştur'u seçin.Select Create custom connector.

    Özel bağlayıcı özellikleri

  3. Genel sekmesinde, özel bağlayıcıyı nasıl oluşturmak istediğinizi seçin.In the General tab, choose how you want to create the custom connector.

    • Bir OpenAPI dosyasını karşıya yükleUpload an OpenAPI file
    • OpenAPI URL'si kullanUse an OpenAPI URL
    • Karşıya Postman Collection V1 yükleUpload Postman Collection V1

      Özel bağlayıcı oluşturma

      Özel bağlayıcınız için bir simgeyi karşıya yükleyin.Upload an icon for your custom connector. Açıklama, Ana bilgisayar ve Temel URL alanları genellikle OpenAPI dosyasından alınan bilgilerle otomatik olarak doldurulur.Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. Otomatik olarak doldurulmazsa bu alanlara bilgi ekleyebilirsiniz.If they are not auto-populated, you can add information to those fields. Devam'ı seçin.Select Continue.

  4. Güvenlik sekmesinde, tüm kimlik doğrulaması özelliklerini girin.In the Security tab, enter any authentication properties.

    Kimlik doğrulaması türleri

    • Kimlik doğrulaması türü, securityDefinitions OpenAPI nesnenizde tanımlananlara göre otomatik olarak doldurulur.The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. Aşağıda bir OAuth2.0 örneği bulunmaktadır.Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • OpenAPI dosyası securityDefintions nesnesini kullanmıyorsa başka bir değer gerekmez.If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • Bir Postman Koleksiyonu kullanılırken kimlik doğrulaması türü alanı, yalnızca OAuth 2.0 veya Temel gibi desteklenen kimlik doğrulama türleri kullanıldığında otomatik olarak doldurulur.When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Azure Active Directory (AAD) kimlik doğrulaması ayarlama örneği için bkz. PowerApps için özel bir Web API'si oluşturma.For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for PowerApps.
  5. Tanım sekmesinde, OpenAPI dosyanızda veya Postman Koleksiyonunuzda tanımlanan tüm işlemler istek ve yanıt değerleri ile birlikte otomatik olarak doldurulur.In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. Gerekli tüm işlemleriniz tanımlanmışsa bu ekranda değişiklik yapmadan kayıt işleminin 6. adımına gidebilirsiniz.If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    Tanım sekmesi

    Mevcut eylemleri düzenlemek veya özel bağlayıcınıza yeni eylemler eklemek istiyorsanız aşağıdaki bölümü okuyun.If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. OpenAPI dosyanızda veya Postman Koleksiyonunuzda bulunmayan yeni bir eylem eklemek istiyorsanız sol bölmedeki Yeni eylem'i seçin ve Genel bölümünde işleminize ilişkin ad, tanım ve görünürlük bilgilerini girin.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. İstek bölümünde sağ üst kısımdaki Örnekten aktar seçeneğini belirleyin.In the Request section, select Import from sample on the top right. Sağdaki forma bir örnek istek yapıştırın.In the form on the right, paste in a sample request. Örnek istekler genellikle Fiil, URL, Üst Bilgiler ve Gövde alanlarını doldurmak için gerekli bilgileri alabileceğiniz API belgesinde mevcuttur.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. Örnek için bkz. Metin Analizi API'si belgeleri.See the Text Analytics API documentation for an example.

      Örnekten aktar

    3. İstek tanımını tamamlamak için İçeri aktar'ı seçin.Select Import to complete the request definition. Benzer şekilde yanıtı tanımlayın.Define the response in a similar way.
  6. Tüm işlemlerinizi tanımladıktan sonra özel bağlayıcınızı oluşturmak için Oluştur'u seçin.Once you have all your operations defined, select Create to create your custom connector.
  7. Özel bağlayıcınızı oluşturduktan sonra API'de tanımlanan işlemleri sınamak için Sına sekmesine gidin.Once you have created your custom connector, go to the Test tab to test the operations defined in the API. Bir bağlantı seçin ve bir işlemi sınamak için giriş parametreleri sağlayın.Choose a connection, and provide input parameters to test an operation.

    Özel bağlayıcıyı sınama

    Çağrı başarılı olursa geçerli bir yanıt alırsınız.If the call is successful, you get a valid response.

    API Yanıtını sınama

Özel bağlayıcınızı kullanmaUse your custom connector

API'nizi kaydettiğinize göre özel bağlayıcıyı (diğer herhangi bir veri kaynağı gibi) uygulamanıza ekleyin.Now that you've registered your API, add the custom connector to your app like you would any other data source. Bu bölümde kısa bir örneği ele alacağız.We'll go through a brief example here. Veri bağlantıları hakkında daha fazla bilgi için bkz. PowerApps'te bir veri bağlantısı ekleme.For more information about data connections, see Add a data connection in PowerApps.

  1. PowerApps Studio'daki sağ bölmede Veri kaynağı ekle'ye tıklayın veya dokunun.In PowerApps Studio, in the right pane, click or tap Add data source.

  2. Oluşturduğunuz özel bağlayıcıya tıklayın veya dokunun.Click or tap the custom connector that you created.

  3. Bağlandığınız hizmette oturum açmak için gerekli tüm adımları tamamlayın.Complete any steps necessary to sign in to the service you're connecting to. API'niz OAuth kimlik doğrulaması kullanıyorsa bir oturum açma ekranı ile karşılaşabilirsiniz.If your API uses OAuth authentication, you might be presented a sign-in screen. API anahtarı kimlik doğrulaması için bir anahtar değeri girmeniz istenebilir.For API key authentication, you might be prompted for a key value.
  4. Uygulamanızda API'yi çağırın.Call the API in your app. Örneğin, Bilişsel Hizmetler'e metin gönderen ve 0 ile 1 arasında bir yaklaşım puanı (uygulamanın yüzde olarak görüntülediği) alan bir uygulama oluşturduk.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.

    • Bu bağlayıcı ile formül çubuğuna "Az" yazmaya başlarsanız uygulamanın kullanıma sunduğu API'yi ve işlemleri görürsünüz.With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • Tam çağrı aşağıdaki gibi görünür. Buraya, TextInput denetimindeki metni geçirerek uygulamada görüntülemek üzere bir puan alırız: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)
      
    • Döndürülen verileri işlemek için uygulamada çok karmaşık olmayan birkaç işlem daha gerçekleştiririz.We do a little more work in the app to handle the data that comes back, but it's not too complicated.

Tamamlanmış uygulama aşağıda yer alan görüntüdeki gibidir.The finished app looks like the following image. Bu basit bir uygulama olmasına rağmen özel bir bağlayıcı aracılığıyla Bilişsel Hizmetler çağrısı yapabilmesi ona güçlü bir işlevsellik kazandırmıştır.It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

Kota ve azaltmaQuota and throttling

  • Özel bağlayıcı oluşturma kotalarına ilişkin ayrıntılar için PowerApps Fiyatlandırması sayfasına bakın.See the PowerApps Pricing page for details about custom connector creation quotas. Sizinle paylaşılan özel bağlayıcılar bu kotaya dahil edilmez.Custom connectors that are shared with you don't count against this quota.
  • Özel bir bağlayıcı ile oluşturulan her bağlantı için kullanıcılar dakikada 500'e kadar istek oluşturabilir.For each connection created on a custom connector, users can make up to 500 requests per minute.

Özel bağlayıcınızı paylaşmaShare your custom connector

Özel bir bağlayıcınız olduğuna göre artık bunu, kuruluşunuzdaki diğer kullanıcılar ile paylaşabilirsiniz.Now that you have a custom connector, you can share it with other users in your organization. Bir API'yi paylaştığınızda diğerlerinin bu API'ye bağlı işlemler yapmaya başlayabileceğini unutmayın. Ayrıca özel bir bağlayıcının silinmesi tüm API bağlantılarının silinmesine neden olur.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. Kuruluşunuzun dışındaki kullanıcılar için bir bağlayıcı sağlamak istiyorsanız bkz. PowerApps'te özel bağlayıcıları onaylamaya genel bakış.If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. powerapps.com adresindeki sol menüde Bağlantılar'ı seçin.In powerapps.com, in the left menu, select Connections. Üç nokta (...) simgesini seçin ve ardından sağ üst köşedeki Özel bağlayıcıları yönet'i seçin.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Yeni bağlantı

  2. Bağlayıcınıza ilişkin üç nokta (. . .) düğmesini ve ardından Özellikleri göster'i seçin.Select the ellipsis (. . .) button for your connector, then select View properties.

    Bağlayıcı özelliklerini görüntüleme

  3. API'nizi ve ardından Paylaş'ı seçin ve API'nize erişim izni vermek istediğiniz kullanıcıları veya grupları girin.Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    Özel bağlayıcı paylaşma

  4. Kaydet'i seçin.Select Save.

Sonraki adımlarNext steps

Postman Koleksiyonu oluşturmayı öğrenmeLearn how to create a Postman Collection

ASP.NET Web API'si kullanma.Use an ASP.NET Web API.

Azure Resource Manager API'si kaydetme.Register an Azure Resource Manager API.