`DocumentAnalysisClient` and `ClassifyDocumentOptions` are inconsistent over different client SDKs

[pnoyens]

• Package Name: @azure/ai-form-recognizer
• Package Version: 5.0.0
• Operating system: MacOS Sonoma 14.5
• [x] nodejs
  • version: v20.13.1
• [ ] browser
  • name/version:
• [x] typescript
  • version: v4.2.3
• Is the bug related to documentation in
  • [ ] README.md
  • [ ] source code documentation
  • [x] SDK API docs on https://docs.microsoft.com

Describe the bug The documentation and implementation are unclear for DocumentAnalysisClient and ClassifyDocumentOptions.

When working in a TypeScript environment on NodeJS, it seems impossible to pass the pages query parameter to the beginClassifyDocument(FromUrl) function. However, when looking into the latest docs for the Python SDK, this is mentioned to be possible (https://learn.microsoft.com/en-us/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.documentanalysisclient?view=azure-python#azure-ai-formrecognizer-documentanalysisclient-begin-classify-document-from-url). At the same time, none of these options are mentioned in the JS docs, or even in the REST specification (https://learn.microsoft.com/en-us/rest/api/aiservices/document-classifiers/classify-document?view=rest-aiservices-v4.0%20(2024-02-29-preview)&tabs=HTTP).

This seems very weird, as the UI within Azure Document Intelligence Studio offers the possibility to define a range of pages to be analysed/classified when testing the models. This made me look into the network tab, and indeed a pages query parameter is passed to the classify endpoint (POST /documentintelligence/documentClassifiers/{modelid}:analyze). For now, I'm using this in my code with success, but it would be nice to know what is happening here and if this parameter will be completely deprecated in the future. In our situation, we classify documents based on the first page only, which works fine and fast. The solution can be found below and works (for now).

To Reproduce Steps to reproduce the behavior:

1. Try passing pages parameter via JS SDK; it will not be used in the underlying call to the analyze endpoint and is not recognized by the TS type of ClassifyDocumentOptions

Expected behavior Consistent behaviour and implementation across SDKs and REST endpoints

Additional context The solution we worked out:

analyze = async (fileUrl: string, modelId: string): Promise<string> => {
    const response = await this.provider.restClient.post(
      `/documentintelligence/documentClassifiers/${modelId}:analyze?pages=1&api-version=${this.configService.get<string>(
        'DOCUMENT_CLASSIFIER_API_VERSION',
      )}`,
      { urlSource: fileUrl },
    );
    return response.headers['operation-location'];
  };

[github-actions[bot]]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @ctstone @vkurpad.