Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[formrecognizer] Add Identity Documents APIs #17128

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions sdk/formrecognizer/azure-ai-formrecognizer/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

**New features**

- New methods `begin_recognize_id_documents` and `begin_recognize_id_documents_from_url` introduced to the SDK. Use these methods to recognize data from identity documents.
- Content-type `image/bmp` now supported by custom forms and training methods.

**Dependency Updates**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,121 @@ def begin_recognize_business_cards_from_url(self, business_card_url, **kwargs):
)
raise e

@distributed_trace
def begin_recognize_id_documents(self, id_document, **kwargs):
# type: (Union[bytes, IO[bytes]], Any) -> LROPoller[List[RecognizedForm]]
"""Extract field text and semantic values from a given ID document.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO

:param id_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
:type id_document: bytes or IO[bytes]
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword content_type: Content-type of the body sent to the API. Content-type is
auto-detected, but can be overridden by passing this keyword argument. For options,
see :class:`~azure.ai.formrecognizer.FormContentType`.
:paramtype content_type: str or ~azure.ai.formrecognizer.FormContentType
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an LROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:

.. versionadded:: v2.1-preview
The *begin_recognize_id_documents* client method

.. admonition:: Example:

.. literalinclude:: ../samples/sample_recognize_id_documents.py
:start-after: [START recognize_id_documents]
:end-before: [END recognize_id_documents]
:language: python
:dedent: 8
:caption: Recognize ID document fields.
"""
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_id_documents_from_url() to analyze an ID document from a URL."
)
if content_type is None and kwargs.get("continuation_token", None) is None:
content_type = get_content_type(id_document)

include_field_elements = kwargs.pop("include_field_elements", False)

try:
return self._client.begin_analyze_id_document_async( # type: ignore
file_stream=id_document,
content_type=content_type,
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents' is only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace
def begin_recognize_id_documents_from_url(self, id_document_url, **kwargs):
# type: (str, Any) -> LROPoller[List[RecognizedForm]]
"""Extract field text and semantic values from a given ID document.
The input document must be the location (URL) of the ID document to be analyzed.

See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO

:param str id_document_url: The URL of the ID document to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an LROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.LROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:

.. versionadded:: v2.1-preview
The *begin_recognize_id_documents_from_url* client method
"""

include_field_elements = kwargs.pop("include_field_elements", False)

try:
return self._client.begin_analyze_id_document_async( # type: ignore
file_stream={"source": id_document_url},
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents_from_url' is "
"only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace
def begin_recognize_invoices(self, invoice, **kwargs):
# type: (Union[bytes, IO[bytes]], Any) -> LROPoller[List[RecognizedForm]]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,124 @@ async def begin_recognize_business_cards_from_url(
)
raise e

@distributed_trace_async
async def begin_recognize_id_documents(
self, id_document: Union[bytes, IO[bytes]], **kwargs: Any
) -> AsyncLROPoller[List[RecognizedForm]]:
"""Extract field text and semantic values from a given ID document.
The input document must be of one of the supported content types - 'application/pdf',
'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO

:param id_document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
:type id_document: bytes or IO[bytes]
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword content_type: Content-type of the body sent to the API. Content-type is
auto-detected, but can be overridden by passing this keyword argument. For options,
see :class:`~azure.ai.formrecognizer.FormContentType`.
:paramtype content_type: str or ~azure.ai.formrecognizer.FormContentType
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.AsyncLROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:

.. versionadded:: v2.1-preview
The *begin_recognize_id_documents* client method

.. admonition:: Example:

.. literalinclude:: ../samples/async_samples/sample_recognize_id_documents_async.py
:start-after: [START recognize_id_documents_async]
:end-before: [END recognize_id_documents_async]
:language: python
:dedent: 8
:caption: Recognize ID documents from a file.
"""
content_type = kwargs.pop("content_type", None)
if content_type == "application/json":
raise TypeError(
"Call begin_recognize_id_documents_from_url() to analyze an ID document from a URL."
)

include_field_elements = kwargs.pop("include_field_elements", False)

if content_type is None and kwargs.get("continuation_token", None) is None:
content_type = get_content_type(id_document)

try:
return await self._client.begin_analyze_id_document_async( # type: ignore
file_stream=id_document,
content_type=content_type,
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents' is only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace_async
async def begin_recognize_id_documents_from_url(
self, id_document_url: str, **kwargs: Any
) -> AsyncLROPoller[List[RecognizedForm]]:
"""Extract field text and semantic values from a given ID document.
The input document must be the location (URL) of the ID document to be analyzed.

See fields found on an ID document here:
https://aka.ms/formrecognizer/TODO

:param str id_document_url: The URL of the ID document to analyze. The input must be a valid, encoded URL
of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
:keyword bool include_field_elements:
Whether or not to include all lines per page and field elements such as lines, words,
and selection marks for each form field.
:keyword int polling_interval: Waiting time between two polls for LRO operations
if no Retry-After header is present. Defaults to 5 seconds.
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
:keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
`pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
:return: An instance of an AsyncLROPoller. Call `result()` on the poller
object to return a list[:class:`~azure.ai.formrecognizer.RecognizedForm`].
:rtype: ~azure.core.polling.AsyncLROPoller[list[~azure.ai.formrecognizer.RecognizedForm]]
:raises ~azure.core.exceptions.HttpResponseError:

.. versionadded:: v2.1-preview
The *begin_recognize_id_documents_from_url* client method
"""

include_field_elements = kwargs.pop("include_field_elements", False)

try:
return await self._client.begin_analyze_id_document_async( # type: ignore
file_stream={"source": id_document_url},
include_text_details=include_field_elements,
cls=kwargs.pop("cls", self._prebuilt_callback),
polling=True,
**kwargs
)
except ValueError as e:
if "begin_analyze_id_document_async" in str(e):
raise ValueError(
"Method 'begin_recognize_id_documents_from_url' is "
"only available for API version V2_1_PREVIEW and up"
)
raise e

@distributed_trace_async
async def begin_recognize_invoices(
self, invoice: str, **kwargs: Any
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
interactions:
- request:
body: xx
headers:
Accept:
- application/json
Accept-Encoding:
- gzip, deflate
Connection:
- keep-alive
Content-Length:
- '2'
Content-Type:
- image/jpeg
User-Agent:
- azsdk-python-ai-formrecognizer/3.1.0b4 Python/3.8.5 (Windows-10-10.0.19041-SP0)
method: POST
uri: https://region.api.cognitive.microsoft.com/formrecognizer/v2.1-preview.3/prebuilt/idDocument/analyze?includeTextDetails=false
response:
body:
string: '{"error": {"code": "401", "message": "Access denied due to invalid
subscription key or wrong API endpoint. Make sure to provide a valid key for
an active subscription and use a correct regional API endpoint for your resource."}}'
headers:
content-length:
- '224'
date:
- Fri, 05 Mar 2021 17:44:04 GMT
status:
code: 401
message: PermissionDenied
version: 1
Loading