Contoh: Membuat keterampilan kustom menggunakan Python (Diarsipkan)

Contoh ini diarsipkan dan tidak didukung. Ini menjelaskan cara membuat keterampilan kustom API web menggunakan Python dan Visual Studio Code. Contoh menggunakan Azure Function yang mengimplementasikan antarmuka keahlian khusus.

Prasyarat

• Tinjau antarmuka keterampilan kustom untuk memeriksa input dan output yang harus diimplementasikan oleh keterampilan kustom.

• Siapkan lingkungan Anda. Kami mengikuti Quickstart: Membuat fungsi di Azure dengan Python menggunakan Visual Studio Code untuk menyiapkan fungsi Azure tanpa server menggunakan Visual Studio Code dan ekstensi Python. Panduan memulai cepat mengarahkan Anda melalui penginstalan alat dan komponen berikut:

  • Python 3.75 atau yang lebih baru
  • Visual Studio Code
  • ekstensi Python untuk Visual Studio Code
  • Azure Functions Core Tools
  • ekstensi Azure Functions untuk Visual Studio Code

Membuat Azure Function

Contoh ini menggunakan Azure Function untuk menunjukkan konsep hosting API web, tetapi pendekatan lain dimungkinkan. Selama Anda memenuhi persyaratan antarmuka untuk keterampilan kognitif, pendekatan yang Anda ambil tidak penting. Azure Functions, bagaimanapun, memudahkan untuk membuat keterampilan kustom.

Membuat proyek untuk fungsi

Templat proyek Azure Functions di Visual Studio Code membuat proyek lokal yang dapat diterbitkan ke aplikasi fungsi di Azure. Aplikasi fungsi memungkinkan Anda mengelompokkan fungsi sebagai unit logis untuk manajemen, penyebaran, dan berbagi sumber daya.

1. Di Visual Studio Code, tekan F1 untuk membuka palet perintah. Di palet perintah, cari dan pilih Azure Functions: Create new project....
2. Pilih lokasi direktori untuk ruang kerja proyek Anda dan pilih Pilih. Jangan gunakan folder proyek yang sudah menjadi bagian dari ruang kerja lain.
3. Pilih bahasa untuk proyek aplikasi fungsi Anda. Untuk tutorial ini, pilih Python.
4. Pilih versi Python (versi 3.7.5 didukung oleh Azure Functions).
5. Pilih templat untuk fungsi pertama proyek Anda. Pilih pemicu HTTP untuk membuat fungsi yang dipicu HTTP di aplikasi fungsi baru.
6. Berikan nama fungsi. Dalam hal ini, mari kita gunakan Concatenator
7. Pilih Fungsi sebagai tingkat Otorisasi. Anda akan menggunakan kunci akses fungsi untuk memanggil titik akhir HTTP fungsi.
8. Tentukan bagaimana Anda ingin membuka proyek Anda. Untuk langkah ini, pilih Tambahkan ke ruang kerja untuk membuat aplikasi fungsi di ruang kerja saat ini.

Visual Studio Code membuat proyek aplikasi fungsi di ruang kerja baru. Proyek ini berisi file host.json dan local.settings.jsonconfiguration, ditambah file proyek khusus bahasa apa pun.

Fungsi baru yang dipicu oleh HTTP juga dibuat di dalam folder Concatenator proyek aplikasi fungsi. Di dalamnya akan ada file yang disebut "__init__.py", dengan konten ini:

import logging

import azure.functions as func


def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

    name = req.params.get('name')
    if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

    if name:
        return func.HttpResponse(f"Hello {name}!")
    else:
        return func.HttpResponse(
             "Please pass a name on the query string or in the request body",
             status_code=400
        )

Sekarang mari kita ubah kode tersebut untuk mengikuti antarmuka keterampilan kustom. Ganti kode default dengan konten berikut:

import logging
import azure.functions as func
import json

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

    try:
        body = json.dumps(req.get_json())
    except ValueError:
        return func.HttpResponse(
             "Invalid body",
             status_code=400
        )
    
    if body:
        result = compose_response(body)
        return func.HttpResponse(result, mimetype="application/json")
    else:
        return func.HttpResponse(
             "Invalid body",
             status_code=400
        )


def compose_response(json_data):
    values = json.loads(json_data)['values']
    
    # Prepare the Output before the loop
    results = {}
    results["values"] = []
    
    for value in values:
        output_record = transform_value(value)
        if output_record != None:
            results["values"].append(output_record)
    return json.dumps(results, ensure_ascii=False)

## Perform an operation on a record
def transform_value(value):
    try:
        recordId = value['recordId']
    except AssertionError  as error:
        return None

    # Validate the inputs
    try:         
        assert ('data' in value), "'data' field is required."
        data = value['data']        
        assert ('text1' in data), "'text1' field is required in 'data' object."
        assert ('text2' in data), "'text2' field is required in 'data' object."
    except AssertionError  as error:
        return (
            {
            "recordId": recordId,
            "errors": [ { "message": "Error:" + error.args[0] }   ]       
            })

    try:                
        concatenated_string = value['data']['text1'] + " " + value['data']['text2']  
        # Here you could do something more interesting with the inputs

    except:
        return (
            {
            "recordId": recordId,
            "errors": [ { "message": "Could not complete operation for record." }   ]       
            })

    return ({
            "recordId": recordId,
            "data": {
                "text": concatenated_string
                    }
            })

Metode transform_value melakukan operasi pada satu rekaman. Anda dapat memodifikasi metode untuk memenuhi kebutuhan spesifik Anda. Ingatlah untuk melakukan validasi input yang diperlukan dan untuk mengembalikan kesalahan dan peringatan jika operasi tidak dapat diselesaikan.

Debug kode Anda secara lokal

Visual Studio Code memudahkan untuk men-debug kode. Tekan 'F5' atau buka menu Debug dan pilih Mulai Pemecahan Masalah.

Anda dapat mengatur breakpoint apa pun pada kode dengan menekan 'F9' pada baris yang diinginkan.

Setelah Anda mulai men-debug, fungsi Anda akan berjalan secara lokal. Anda dapat menggunakan alat seperti Postman atau Fiddler untuk mengeluarkan permintaan ke localhost. Perhatikan lokasi titik akhir lokal Anda di jendela Terminal.

Membuat aplikasi fungsi di Azure

Ketika Anda puas dengan perilaku fungsi, Anda dapat menerbitkannya. Sejauh ini Anda telah bekerja secara lokal. Di bagian ini, Anda akan membuat aplikasi fungsi di Azure lalu menyebarkan proyek lokal ke aplikasi yang Anda buat.

Membuat aplikasi dari Visual Studio Code

1. Di Visual Studio Code, tekan F1 untuk membuka palet perintah. Di palet perintah, cari dan pilih Buat Aplikasi Fungsi di Azure.

2. Jika Anda memiliki beberapa langganan aktif, pilih langganan untuk aplikasi ini.

3. Masukkan nama unik global untuk aplikasi fungsi. Ketik nama yang valid untuk URL.

4. Pilih stack runtime dan pilih versi bahasa yang Anda gunakan secara lokal.

5. Pilih lokasi untuk aplikasi Anda. Jika memungkinkan, pilih wilayah yang sama yang juga menghosting layanan pencarian Anda.

Dibutuhkan beberapa menit untuk membuat aplikasi. Setelah siap, Anda akan melihat aplikasi baru di bawah Sumber Daya dan Aplikasi Fungsi dari langganan aktif.

Menyebarkan ke Azure

1. Masih di Visual Studio Code, tekan F1 untuk membuka palet perintah. Di palet perintah, cari dan pilih Sebarkan ke Aplikasi Fungsi....

2. Pilih aplikasi fungsi yang Anda buat.

3. Konfirmasikan bahwa Anda ingin melanjutkan, lalu pilih Sebarkan. Anda dapat memantau status penyebaran di jendela output.

4. Pindah ke portal Microsoft Azure , navigasikan ke Semua Sumber. Cari aplikasi fungsi yang Anda sebarkan menggunakan nama unik global yang Anda berikan di langkah sebelumnya.

   Saran

   Anda juga dapat mengklik kanan aplikasi fungsi di Visual Studio Code dan memilih Buka di Portal.

5. Di portal, di sebelah kiri, pilih Functions, lalu pilih fungsi yang Anda buat.

6. Di halaman gambaran umum fungsi, pilih Dapatkan URL Fungsi di bilah perintah di bagian atas. Ini akan memungkinkan Anda menyalin URL untuk memanggil fungsi.

   

Menguji fungsi di Azure

Menggunakan kunci host default dan URL yang Anda salin, uji fungsi Anda dari dalam portal Microsoft Azure.

1. Di sebelah kiri, di bawah Pengembang, pilih kode + Uji.

2. Pilih Uji/Jalankan di bilah perintah.

3. Untuk input, gunakan Post, kunci default, lalu tempelkan di isi permintaan:

   {
       "values": [
           {
               "recordId": "e1",
               "data":
               {
                   "text1":  "Hello",
                   "text2":  "World"
               }
           },
           {
               "recordId": "e2",
               "data": "This is an invalid input"
           }
       ]
   }
   

4. Pilih Jalankan.

   

Contoh ini harus menghasilkan hasil yang sama dengan yang Anda lihat sebelumnya saat menjalankan fungsi di lingkungan lokal.

Menambahkan ke set keterampilan

Sekarang setelah Anda memiliki keterampilan kustom baru, Anda dapat menambahkannya ke set keterampilan Anda. Contoh di bawah ini menunjukkan kepada Anda cara memanggil keterampilan untuk menggabungkan Judul dan Penulis dokumen ke dalam satu bidang, yang kami sebut merged_title_author.

Ganti [your-function-url-here] dengan URL Azure Function baru Anda.

{
    "skills": [
      "[... other existing skills in the skillset are here]",  
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "Our new search custom skill",
        "uri": "https://[your-function-url-here]",        
          "context": "/document/merged_content/organizations/*",
          "inputs": [
            {
              "name": "text1",
              "source": "/document/metadata_title"
            },
            {
              "name": "text2",
              "source": "/document/metadata_author"
            },
          ],
          "outputs": [
            {
              "name": "text",
              "targetName": "merged_title_author"
            }
          ]
      }
  ]
}

Ingatlah untuk menambahkan "outputFieldMapping" dalam definisi pengindeks untuk mengirim "merged_title_author" ke bidang "nama lengkap" di indeks pencarian.

"outputFieldMappings": [
    {
        "sourceFieldName": "/document/content/merged_title_author",
        "targetFieldName": "fullname"
    }
]