Hızlı Başlangıç: REST API | Önizleme

  • Makale
  • Okumak için 9 dakika

Not

Form Tanıma v3.0 şu anda genel önizlemededir. Bazı özellikler desteklenmiyor veya sınırlı özelliklere sahip olabilir.

| Form Tanıma REST API | Azure REST API başvurusu |

Kullanmaya başlayın C# Form Tanıma kullanarak Azure Form Tanıma ile birlikte kullanın. Azure Form Tanıma, belgelerinizin form alanlarını, metinlerini ve tablolarını ayıklamak ve analiz etmek için makine öğrenmesini kullanan bulut tabanlı bir Azure Uygulamalı AI Hizmetidir. İstemci kitaplığı SDK'larımızı iş akışlarınıza ve uygulamalarınıza tümleştirerek Form Tanıma modellerini kolayca çağırabilirsiniz. Teknolojiyi öğrenerek ücretsiz hizmeti kullanmalarını öneririz. Ücretsiz sayfa sayısının aylık 500 ile sınırlı olduğunu unutmayın.

Yeni özellikler ve geliştirme Form Tanıma daha fazla bilgi edinmek için Genel Bakış sayfamızı ziyaret edin.

Form Tanıma modelleri

Bu REST API aşağıdaki modelleri ve özellikleri destekler:

  • 🆕Genel belge—Metin, tablo, yapı, anahtar-değer çiftleri ve adlandırılmış varlıkları analiz edip ayıkla.|
  • Düzen—Model eğitmeden tabloları, satırları, sözcükleri ve radyo düğmeleri ve form belgelerinden onay kutuları gibi seçim işaretlerini analiz edip ayıklar.
  • Özel—Kendi form türleriyle eğitilmiş modelleri kullanarak form alanlarını ve özel formlar elde edilen diğer içerikleri analiz edip ayıklar.
  • Faturalar: Önceden eğitilmiş bir fatura modelini kullanarak faturalardan yaygın alanları analiz edip ayıklar.
  • Makbuzlar— Önceden eğitilmiş makbuz modelini kullanarak makbuzlardan ortak alanları analiz edip ayıklar.
  • Kimlik belgeleri—Önceden eğitilmiş kimlik belgeleri modelini kullanarak kimlik belgelerinden( passport veya sürücü lisansları gibi) ortak alanları analiz edip ayıklar.
  • Kartvizitler: Önceden eğitilmiş bir kartvizit modelini kullanarak kartvizitlerden ortak alanları analiz etme ve ayıklama.

Belgeyi analiz etme

Form Tanıma v3.0, POST ve GET işlemlerine atadığınız düzen, önceden oluşturulmuş modeller ve özel modeller için analiz belgesi ile analiz sonucu (GET) işlemlerini tek bir işlem çifti halinde  modelIds bir arada sağlar:

POST /documentModels/{modelId}:analyze

GET /documentModels/{modelId}/analyzeResults/{resultId}

Aşağıdaki tabloda, REST API çağrıları için güncelleştirmeler yer almaktadır.

Özellik v2.1 v3.0
Genel belge yok /documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Fatura /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Makbuz /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Kimlik belgesi /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Kartvizit /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
Özel /custom/{modelId}/analyze /documentModels/{modelId}:analyze

Bu hızlı başlangıçta formlardan ve belgelerden verileri ve değerleri analiz etmek ve ayıklamak için aşağıdaki özellikleri kullanacağız:

  • 🆕 - Metin,tablo, yapı, anahtar-değer çiftleri ve adlandırılmış varlıkları analiz edip ayıklar.

  • Düzen—Model eğitmeden tabloları, satırları, sözcükleri ve radyo düğmeleri ve form belgelerinden onay kutuları gibi seçim işaretlerini analiz edip ayıklar.

  • Önceden Oluşturulmuş Model— Önceden eğitilmiş bir modeli kullanarak ortak belge türlerinden verileri analiz etme ve ayıklama.

Önkoşullar

  • Azure aboneliği - Ücretsiz bir abonelik oluşturun

  • cURL yüklü.

  • PowerShell sürüm 6.0+veya benzer bir komut satırı uygulaması.

  • Bilişsel Hizmetler veya Form Tanıma kaynak. Azure aboneliğinize sahip olduktan sonra, anahtarınızı ve uç noktanızı almak için Form Tanıma tek hizmetli veya çok Azure portal kaynak oluşturun. Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek üzere ücretsiz fiyatlandırma katmanını ( F0 ) kullanabilirsiniz.

İpucu

Tek bir uç nokta/anahtar altında birden çok bilişsel hizmetlere erişmeyi planlıyorsanız Bilişsel Hizmetler kaynağı oluşturun. Yalnızca Form Tanıma erişim için bir Form Tanıma oluşturun. Kimlik doğrulamasını kullanmak için tek hizmetli bir kaynağa ihtiyacınız Azure Active Directory unutmayın.

  • Kaynağınız dağıt edildikten sonra Kaynağa git'i seçin. Uygulamanıza api'sini bağlamak için, kaynakta yer alan anahtara ve uç Form Tanıma gerekir. Hızlı başlangıçta anahtarınızı ve uç noktanızı aşağıdaki koda yapıştırabilirsiniz:

    Ekran görüntüsü: Anahtarlar ve uç nokta konumu Azure portal.

Uygulamanıza kopyalayıp yapıştırmak için bir kod örneği seçin:

Önemli

Bitirilen anahtarı kodunuzdan kaldırmayı unutmayın ve hiçbir zaman herkese açık şekilde yayınlayamayabilirsiniz. Üretim için, kimlik bilgilerinizi depolamak ve erişmek için güvenli yöntemler kullanın. Daha fazla bilgi için Bilişsel Hizmetler güvenliği makalesine bakın.

Deneyin: Genel belge modeli

  • Bu örnekte, URI'de bir form belgesi dosyası gerekir. Bu hızlı başlangıç için örnek form belgemizi kullanabilirsiniz. Komutunu çalıştırmadan önce şu değişiklikleri yapın:
  1. yerine {endpoint} kendi aboneliğinizi almak için Form Tanıma değiştirin.
  2. yerine {subscription key} önceki adımda kopyalanan abonelik anahtarını alın.
  3. yerine {your-document-url} örnek form belgesi URL'si yazın.

İstek

curl -v -i POST "https://{endpoint}/formrecognizer/documentModels/prebuilt-document:analyze?api-version=2021-09-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

Operation-Location

202 (Success)Operation-Location üst bilgisi içeren bir yanıt alırsınız. Bu üst bilgi değeri, zaman uyumsuz işlem durumunu sorgulamak ve sonuçları almak için kullanabileceğiniz bir sonuç kimliği içerir:

https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview

Genel belge sonuçlarını al

Belgeyi çözümle API'sini çağırdıktan sonra, işlemi ve ayıklanan verileri almak için Analiz sonucu al API'sini çağırabilirsiniz. Komutunu çalıştırmadan önce şu değişiklikleri yapın:

  1. yerine {endpoint} kendi aboneliğinizi almak için Form Tanıma değiştirin.
  2. yerine {subscription key} önceki adımda kopyalanan abonelik anahtarını alın.
  3. yerine {resultId} önceki adımda yer alan sonuç kimliğini girin.

İstek

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/prebuilt-document/analyzeResults/{resultId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Yanıtı inceleme

200 (Success)JSON çıkışıyla bir yanıt alırsınız. İlk alan "status" olan , işlemi durumunu gösterir. İşlem tamamlanmazsa değeri veya olur ve API'yi el ile veya betik "status" "running" aracılığıyla yeniden "notStarted" çağırmanız gerekir. Çağrılar arasında bir saniye veya daha fazla aralık önerilir.

Düğüm "analyzeResults" tanınan tüm metinleri içerir. Metin sayfa, satırlar, tablolar, anahtar-değer çiftleri ve varlıklara göre düzenlenmiştir.

Örnek yanıt

{
    "status": "succeeded",
    "createdDateTime": "2021-09-28T16:52:51Z",
    "lastUpdatedDateTime": "2021-09-28T16:53:08Z",
    "analyzeResult": {
        "apiVersion": "2021-09-30-preview",
        "modelId": "prebuilt-document",
        "stringIndexType": "textElements",
        "content": "content extracted",
        "pages": [
            {
                "pageNumber": 1,
                "angle": 0,
                "width": 8.4722,
                "height": 11,
                "unit": "inch",
                "words": [
                    {
                        "content": "Case",
                        "boundingBox": [
                            1.3578,
                            0.2244,
                            1.7328,
                            0.2244,
                            1.7328,
                            0.3502,
                            1.3578,
                            0.3502
                        ],
                        "confidence": 1,
                        "span": {
                            "offset": 0,
                            "length": 4
                        }
                    }

                ],
                "lines": [
                    {
                        "content": "Case",
                        "boundingBox": [
                            1.3578,
                            0.2244,
                            3.2879,
                            0.2244,
                            3.2879,
                            0.3502,
                            1.3578,
                            0.3502
                        ],
                        "spans": [
                            {
                                "offset": 0,
                                "length": 22
                            }
                        ]
                    }
                ]
            }
        ],
        "tables": [
            {
                "rowCount": 8,
                "columnCount": 3,
                "cells": [
                    {
                        "kind": "columnHeader",
                        "rowIndex": 0,
                        "columnIndex": 0,
                        "rowSpan": 1,
                        "columnSpan": 1,
                        "content": "Applicant's Name:",
                        "boundingRegions": [
                            {
                                "pageNumber": 1,
                                "boundingBox": [
                                    1.9198,
                                    4.277,
                                    3.3621,
                                    4.2715,
                                    3.3621,
                                    4.5034,
                                    1.9198,
                                    4.5089
                                ]
                            }
                        ],
                        "spans": [
                            {
                                "offset": 578,
                                "length": 17
                            }
                        ]
                    }
                ],
                "spans": [
                    {
                        "offset": 578,
                        "length": 300
                    },
                    {
                        "offset": 1358,
                        "length": 10
                    }
                ]
            }
        ],
        "keyValuePairs": [
            {
                "key": {
                    "content": "Case",
                    "boundingRegions": [
                        {
                            "pageNumber": 1,
                            "boundingBox": [
                                1.3578,
                                0.2244,
                                1.7328,
                                0.2244,
                                1.7328,
                                0.3502,
                                1.3578,
                                0.3502
                            ]
                        }
                    ],
                    "spans": [
                        {
                            "offset": 0,
                            "length": 4
                        }
                    ]
                },
                "value": {
                    "content": "A Case",
                    "boundingRegions": [
                        {
                            "pageNumber": 1,
                            "boundingBox": [
                                1.8026,
                                0.2276,
                                3.2879,
                                0.2276,
                                3.2879,
                                0.3502,
                                1.8026,
                                0.3502
                            ]
                        }
                    ],
                    "spans": [
                        {
                            "offset": 5,
                            "length": 17
                        }
                    ]
                },
                "confidence": 0.867
            }
        ],
        "entities": [
            {
                "category": "Person",
                "content": "Jim Smith",
                "boundingRegions": [
                    {
                        "pageNumber": 1,
                        "boundingBox": [
                            3.4672,
                            4.3255,
                            5.7118,
                            4.3255,
                            5.7118,
                            4.4783,
                            3.4672,
                            4.4783
                        ]
                    }
                ],
                "confidence": 0.93,
                "spans": [
                    {
                        "offset": 596,
                        "length": 21
                    }
                ]
            }
        ],
        "styles": [
            {
                "isHandwritten": true,
                "confidence": 0.95,
                "spans": [
                    {
                        "offset": 565,
                        "length": 12
                    },
                    {
                        "offset": 3493,
                        "length": 1
                    }
                ]
            }
        ]
    }
}

Deneyin: Düzen modeli

Komutunu çalıştırmadan önce şu değişiklikleri yapın:

  1. yerine {endpoint} kendi aboneliğinizi almak için Form Tanıma değiştirin.
  2. yerine {subscription key} önceki adımda kopyalanan abonelik anahtarını alın.
  3. yerine "{your-document-url} örnek URL'lerden birini değiştirin.

İstek

curl -v -i POST "https://{endpoint}/formrecognizer/documentModels/prebuilt-layout:analyze?api-version=2021-09-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

Operation-Location

202 (Success)Operation-Location üst bilgisi içeren bir yanıt alırsınız. Bu üst bilgi değeri, zaman uyumsuz işlem durumunu sorgulamak ve sonuçları almak için kullanabileceğiniz bir sonuç kimliği içerir:

https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/**{resultId}**?api-version=2021-09-30-preview

Düzen sonuçlarını al

Belgeyi çözümle API'sini çağırdıktan sonra, işlemi ve ayıklanan verileri almak için Analiz sonucu al API'sini çağırabilirsiniz. Komutu çalıştırmadan önce Şu değişiklikleri yapın:

  1. {endpoint}Form tanıyıcı aboneliğiniz ile edindiğiniz uç noktayla değiştirin.
  2. {subscription key}Önceki adımdan kopyaladığınız abonelik anahtarıyla değiştirin.
  3. {resultId}Önceki adımdan elde edilen sonuç kimliğiyle değiştirin.

İstek

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/prebuilt-layout/analyzeResults/{resultId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Yanıtı inceleme

200 (Success)JSON çıkışıyla bir yanıt alacaksınız. İlk alan, "status" , işlemin durumunu gösterir. İşlem tamamlanmadıysa, değeri "status" "running" veya olur "notStarted" ve API 'yi el ile ya da bir komut dosyası aracılığıyla tekrar çağırmanız gerekir. Çağrılar arasında bir saniye veya daha fazla Aralık önerilir.

Deneyin: önceden oluşturulmuş model

Bu örnek, örnek olarak bir fatura kullanarak, belirli ortak belge türlerindeki verilerin önceden eğitilen bir modelle nasıl çözümlendiğini gösterir.

  • Bu örnekte, önceden oluşturulmuş bir model kullanarak bir fatura belgesini bir belge olarak analiz ediyoruz. Bu hızlı başlangıç için örnek fatura belgemizi kullanabilirsiniz.

Fatura önceden oluşturulmuş model KIMLIĞINI seçin

Faturanız sınırlandırmadınız — her birinin, kendi desteklenen alanları kümesine sahip arasından seçim yapabileceğiniz birkaç önceden oluşturulmuş model vardır. Çözümle işlemi için kullanılacak model çözümlenecek belge türüne bağlıdır. Form tanıyıcı hizmeti tarafından şu anda desteklenen önceden oluşturulmuş modellerin model kimlikleri şunlardır:

  • önceden oluşturulan-fatura: metin, seçim işaretleri, tablolar, anahtar-değer çiftleri ve faturalardan anahtar bilgilerini ayıklar.
  • önceden oluşturulmuş-businessCard: iş kartlarından metin ve anahtar bilgilerini ayıklar.
  • önceden oluşturulmuş-ıddocument: sürücü lisanlarından ve uluslararası Passport 'tan metin ve anahtar bilgilerini ayıklar.
  • önceden oluşturulmuş alındı: alındılardan metin ve anahtar bilgilerini ayıklar.

Komutu çalıştırmadan önce Şu değişiklikleri yapın:

  1. {endpoint}Form tanıyıcı aboneliğiniz ile edindiğiniz uç noktayla değiştirin.

  2. {subscription key}Önceki adımdan kopyaladığınız abonelik anahtarıyla değiştirin.

  3. \"{your-document-url}Örnek bir fatura URL 'si ile değiştirin:

    https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-invoice.pdf

İstek

curl -v -i POST "https://{endpoint}/formrecognizer/documentModels/prebuilt-invoice:analyze?api-version=2021-09-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

Operation-Location

202 (Success) İşlem konumu üst bilgisi içeren bir yanıt alacaksınız. Bu üstbilginin değeri, zaman uyumsuz işlemin durumunu sorgulamak ve sonuçları almak için kullanabileceğiniz bir sonuç KIMLIĞI içerir:

https://{Host}/formtanıyıcı/Documentmodeller/{ModelId}/analiz Zeresults/{Resultıd}? api-Version = 2021-09 -30-Preview

Fatura sonuçlarını al

Belgeyi çözümle API 'sini çağırdıktan sonra, işlemin durumunu ve ayıklanan verileri almak için Çözümleme sonucunu al API 'sini çağırın. Komutu çalıştırmadan önce Şu değişiklikleri yapın:

  1. {endpoint}Form tanıyıcı aboneliğiniz ile edindiğiniz uç noktayla değiştirin.
  2. {subscription key}Önceki adımdan kopyaladığınız abonelik anahtarıyla değiştirin.
  3. {resultId}Önceki adımdan elde edilen sonuç kimliğiyle değiştirin.

İstek

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/prebuilt-invoice/analyzeResults/{resultId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Yanıtı inceleme

200 (Success)JSON çıkışıyla bir yanıt alacaksınız. İlk alan, "status" , işlemin durumunu gösterir. İşlem tamamlanmadıysa, değeri "status" "running" veya olur "notStarted" ve API 'yi el ile ya da bir komut dosyası aracılığıyla tekrar çağırmanız gerekir. Çağrılar arasında bir saniye veya daha fazla Aralık önerilir.

Sonuçları geliştirme

Düğüm altındaki "confidence" her anahtar/değer sonucu için değerleri "pageResults" inceler. Ayrıca, düğümdeki metin okuma işlemine "readResults" karşılık gelen güven puanlarına da bakmalısiniz. Okuma sonuçlarının güveni, anahtar/değer ayıklama sonuçlarının güvenini etkilemez, bu nedenle her ikisini de denetlemelisiniz.

  • Okuma işlemi için güven puanı düşükse, giriş belgelerinizin kalitesini iyileştirmeyi deneyin (bkz. Giriş gereksinimleri).
  • Anahtar/değer ayıklama işlemi için güven puanları düşükse, analiz edilirken kullanılan belgelerin eğitim kümesinde kullanılan belgelerle aynı türde olduğundan emin olur. Eğitim kümesinde belgelerin görünümü farklı ise, bunları farklı klasörlere bölmeyi ve her varyasyon için bir model eğitmeyi göz önünde bulundurabilirsiniz.

Hedefleyilen güven puanları kullanım örnek durumuna bağlıdır, ancak genellikle %80 veya üzeri bir puanı hedeflemek iyi bir uygulamadır. Tıbbi kayıtların veya fatura hesaplarının okunması gibi daha hassas durumlarda %100 puan önerilir.

Özel modelleri yönetme

Modellerin bir listesini alın

Preview v 3.0  liste modelleri isteği, özel modellerin yanı sıra, önceden oluşturulmuş modellerin disk belleğine alınmış bir listesini döndürür. Yalnızca durumu başarılı olan modeller dahildir. Devam eden veya başarısız olan modeller liste işlemleri isteği aracılığıyla listelenebilir. Varsa, modellerdeki sonraki sayfaya erişmek için nextLink özelliğini kullanın. Desteklenen belgelerin listesi ve alanları da dahil olmak üzere, döndürülen her model hakkında daha fazla bilgi almak için, modeli alIsteğine ModelId geçirin.

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview"

Belirli bir modeli al

Preview v 3.0 Get modeli , belirli bir modelle ilgili bilgileri başarılı bir duruma getirir. Başarısız ve devam eden modeller için, model oluşturma işlemlerinin durumunu ve ortaya çıkan hataları izlemek için Get işlemini kullanın.

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Model silme

Preview v 3.0 model silme isteği özel modeli kaldırır ve ModelId artık gelecekteki işlemler tarafından erişilemez. Yeni modeller çakışma olmadan aynı ModelId kullanılarak oluşturulabilir.

curl -v -X DELETE "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Sonraki adımlar

Bu hızlı başlangıçta, formları farklı yollarla analiz etmek için (v 3.0) form tanıyıcı REST API kullandınız. Daha ayrıntılı bilgi edinmek için, başvuru belgelerini inceleyerek form tanıyıcı API 'sini inceleyin.

REST API Preview (v 3.0) başvuru belgeleri