Skip to content

Commit

Permalink
[FormRecognizer] Rename for cross-language API consistency (Azure#8808)
Browse files Browse the repository at this point in the history 
* [FormRecognizer] Rename for cross-language API consistency

- `beginRecognizeForms` => `beginRecognizeCustomForms`

* FormElement => FormContent

* blobContainerUrl => trainingFilesUrl

* parameter name `documentUrl` => `formFileUrl` or `receiptFileUrl`

* useLabels => useTrainingLabels, getModel => getCustomModel

* listModels => listCustomModels

* ModelInfo => CustomFormModelInfo

* limit => customModelLimit, count => customModelCount

* fieldLabel => labelText

* ErrorInformation => FormRecognizerError

export `Model` from model.ts instead of from generated code.

* CustomFormSubModelField => CustomFormField

* ModelStatus => CustomFormModelStatus

TrainStatus => TrainingStatus
  • Loading branch information
@jeremymeng
jeremymeng authored May 15, 2020
1 parent c10c9ff commit e5cf732
Show file tree
Hide file tree
Showing 20 changed files with 280 additions and 183 deletions.
8 changes: 4 additions & 4 deletions sdk/formrecognizer/ai-form-recognizer/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ async function main() {
const readStream = fs.createReadStream(path);
const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
const poller = await client.beginRecognizeForms(modelId, readStream, "application/pdf", {
const poller = await client.beginRecognizeCustomForms(modelId, readStream, "application/pdf", {
onProgress: (state) => { console.log(`status: ${state.status}`); }
});
await poller.pollUntilDone();
Expand Down Expand Up @@ -315,7 +315,7 @@ async function main() {
const trainingClient = client.getFormTrainingClient();
// returns an async iteratable iterator that supports paging
const result = await trainingClient.listModels();
const result = await trainingClient.listCustomModels();
let i = 0;
for await (const modelInfo of result) {
console.log(`model ${i++}:`);
Expand All @@ -324,7 +324,7 @@ async function main() {
// using `iter.next()`
i = 1;
let iter = trainingClient.listModels();
let iter = trainingClient.listCustomModels();
let modelItem = await iter.next();
while (!modelItem.done) {
console.log(`model ${i++}: ${modelItem.value.modelId}`);
Expand All @@ -333,7 +333,7 @@ async function main() {
// using `byPage()`
i = 1;
for await (const response of trainingClient.listModels().byPage()) {
for await (const response of trainingClient.listCustomModels().byPage()) {
for (const modelInfo of response.modelList) {
console.log(`model ${i++}: ${modelInfo.modelId}`);
}
Expand Down
100 changes: 53 additions & 47 deletions sdk/formrecognizer/ai-form-recognizer/review/ai-form-recognizer.api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ import { RestResponse } from '@azure/core-http';

// @public
export interface AccountProperties {
count: number;
limit: number;
customModelCount: number;
customModelLimit: number;
}

// @public
Expand Down Expand Up @@ -74,32 +74,43 @@ export type ContentPollerLike = PollerLike<PollOperationState<RecognizeContentRe
// @public
export type ContentType = "application/pdf" | "image/jpeg" | "image/png" | "image/tiff";

// @public (undocumented)
export interface CustomFormField {
accuracy?: number;
name: string;
}

// @public
export interface CustomFormModel {
createdOn: Date;
errors?: ErrorInformation[];
errors?: FormRecognizerError[];
lastModified: Date;
modelId: string;
models?: CustomFormSubModel[];
status: ModelStatus;
status: CustomFormModelStatus;
trainingDocuments?: TrainingDocumentInfo[];
}

// @public
export interface CustomFormModelInfo {
createdOn: Date;
lastModified: Date;
modelId: string;
status: CustomFormModelStatus;
}

// @public
export type CustomFormModelStatus = "creating" | "ready" | "invalid";

// @public (undocumented)
export interface CustomFormSubModel {
accuracy?: number;
fields: {
[propertyName: string]: CustomFormSubModelField;
[propertyName: string]: CustomFormField;
};
formType: string;
}

// @public (undocumented)
export interface CustomFormSubModelField {
accuracy?: number;
name: string;
}

// Warning: (ae-forgotten-export) The symbol "CommonFieldValue" needs to be exported by the entry point index.d.ts
//
// @public
Expand All @@ -111,14 +122,6 @@ export type DateFieldValue = {
// @public
export type DeleteModelOptions = FormRecognizerOperationOptions;

// @public (undocumented)
export interface ErrorInformation {
// (undocumented)
code: string;
// (undocumented)
message: string;
}

// @public
export type FieldValue = StringFieldValue | DateFieldValue | TimeFieldValue | PhoneNumberFieldValue | NumberFieldValue | IntegerFieldValue | ArrayFieldValue | ObjectFieldValue;

Expand All @@ -128,10 +131,10 @@ export type FieldValueTypes = string | Date | number | FieldValue[] | {
};

// @public
export type FormElement = FormWord | FormLine;
export type FormContent = FormWord | FormLine;

// @public
export interface FormElementCommon {
export interface FormContentCommon {
boundingBox: Point2D[];
pageNumber: number;
text: string;
Expand All @@ -140,7 +143,7 @@ export interface FormElementCommon {
// @public
export interface FormField {
confidence?: number;
fieldLabel?: FormText;
labelText?: FormText;
name?: string;
value?: FieldValueTypes;
valueText?: FormText;
Expand All @@ -154,15 +157,15 @@ export interface FormFieldsReport {
}

// @public
export interface FormLine extends FormElementCommon {
export interface FormLine extends FormContentCommon {
kind: "line";
words: FormWord[];
}

// @public
export interface FormModel {
keys: KeysResult;
modelInfo: ModelInfo;
modelInfo: CustomFormModelInfo;
trainResult?: FormTrainResult;
}

Expand Down Expand Up @@ -198,11 +201,11 @@ export type FormPollerLike = PollerLike<PollOperationState<RecognizeFormResultRe
export class FormRecognizerClient {
constructor(endpointUrl: string, credential: KeyCredential, options?: FormRecognizerClientOptions);
beginRecognizeContent(data: FormRecognizerRequestBody, contentType?: ContentType, options?: BeginRecognizeContentOptions): Promise<ContentPollerLike>;
beginRecognizeContentFromUrl(documentUrl: string, options?: BeginRecognizeContentOptions): Promise<ContentPollerLike>;
beginRecognizeForms(modelId: string, data: FormRecognizerRequestBody, contentType?: ContentType, options?: BeginRecognizeFormsOptions): Promise<FormPollerLike>;
beginRecognizeFormsFromUrl(modelId: string, documentUrl: string, options?: BeginRecognizeFormsOptions): Promise<PollerLike<PollOperationState<RecognizeFormResultResponse>, RecognizeFormResultResponse>>;
beginRecognizeContentFromUrl(formFileUrl: string, options?: BeginRecognizeContentOptions): Promise<ContentPollerLike>;
beginRecognizeCustomForms(modelId: string, data: FormRecognizerRequestBody, contentType?: ContentType, options?: BeginRecognizeFormsOptions): Promise<FormPollerLike>;
beginRecognizeCustomFormsFromUrl(modelId: string, formFileUrl: string, options?: BeginRecognizeFormsOptions): Promise<PollerLike<PollOperationState<RecognizeFormResultResponse>, RecognizeFormResultResponse>>;
beginRecognizeReceipts(data: FormRecognizerRequestBody, contentType?: ContentType, options?: BeginRecognizeReceiptsOptions): Promise<ReceiptPollerLike>;
beginRecognizeReceiptsFromUrl(documentUrl: string, options?: BeginRecognizeReceiptsOptions): Promise<ReceiptPollerLike>;
beginRecognizeReceiptsFromUrl(receiptFileUrl: string, options?: BeginRecognizeReceiptsOptions): Promise<ReceiptPollerLike>;
readonly endpointUrl: string;
getFormTrainingClient(): FormTrainingClient;
}
Expand All @@ -211,6 +214,12 @@ export class FormRecognizerClient {
export interface FormRecognizerClientOptions extends PipelineOptions {
}

// @public
export interface FormRecognizerError {
code: string;
message: string;
}

// @public
export interface FormRecognizerOperationOptions extends OperationOptions {
}
Expand All @@ -220,7 +229,7 @@ export type FormRecognizerRequestBody = Blob | ArrayBuffer | ArrayBufferView | N

// @public
export interface FormResult {
errors?: ErrorInformation[];
errors?: FormRecognizerError[];
forms?: RecognizedForm[];
version: string;
}
Expand All @@ -243,7 +252,7 @@ export interface FormTableCell {
rowIndex: number;
rowSpan?: number;
text: string;
textContent?: FormElement[];
textContent?: FormContent[];
}

// @public
Expand All @@ -255,28 +264,28 @@ export interface FormTableRow {
export interface FormText {
boundingBox?: Point2D[];
text?: string;
textContent?: FormElement[];
textContent?: FormContent[];
}

// @public
export class FormTrainingClient {
constructor(endpointUrl: string, credential: KeyCredential, options?: FormRecognizerClientOptions);
beginTraining(blobContainerUrl: string, useLabels?: boolean, options?: BeginTrainingOptions<FormModelResponse>): Promise<PollerLike<PollOperationState<FormModelResponse>, FormModelResponse>>;
beginTraining(trainingFilesUrl: string, useTrainingLabels?: boolean, options?: BeginTrainingOptions<FormModelResponse>): Promise<PollerLike<PollOperationState<FormModelResponse>, FormModelResponse>>;
deleteModel(modelId: string, options?: DeleteModelOptions): Promise<RestResponse>;
readonly endpointUrl: string;
getAccountProperties(options?: GetAccountPropertiesOptions): Promise<AccountProperties>;
getModel(modelId: string, options?: GetModelOptions): Promise<FormModelResponse>;
listModels(options?: ListModelsOptions): PagedAsyncIterableIterator<ModelInfo, ListModelsResponseModel>;
getCustomModel(modelId: string, options?: GetModelOptions): Promise<FormModelResponse>;
listCustomModels(options?: ListModelsOptions): PagedAsyncIterableIterator<CustomFormModelInfo, ListModelsResponseModel>;
}

// @public
export interface FormTrainResult {
errors?: ErrorInformation[];
errors?: FormRecognizerError[];
trainingDocuments: TrainingDocumentInfo[];
}

// @public
export interface FormWord extends FormElementCommon {
export interface FormWord extends FormContentCommon {
confidence?: number;
containingLine?: FormLine;
kind: "word";
Expand Down Expand Up @@ -348,7 +357,7 @@ export interface ModelInfo {
createdOn: Date;
lastModified: Date;
modelId: string;
status: ModelStatus;
status: CustomFormModelStatus;
}

// @public
Expand All @@ -365,9 +374,6 @@ export interface ModelsSummary {
limit: number;
}

// @public
export type ModelStatus = "creating" | "ready" | "invalid";

// @public
export type NumberFieldValue = {
type: "number";
Expand Down Expand Up @@ -534,11 +540,14 @@ export type TimeFieldValue = {
// @public
export interface TrainingDocumentInfo {
documentName: string;
errors: ErrorInformation[];
errors: FormRecognizerError[];
pageCount: number;
status: TrainStatus;
status: TrainingStatus;
}

// @public
export type TrainingStatus = "succeeded" | "partiallySucceeded" | "failed";

// @public
export type TrainModelOptions = FormRecognizerOperationOptions & {
prefix?: string;
Expand All @@ -548,14 +557,11 @@ export type TrainModelOptions = FormRecognizerOperationOptions & {
// @public
export interface TrainResult {
averageModelAccuracy?: number;
errors?: ErrorInformation[];
errors?: FormRecognizerError[];
fields?: FormFieldsReport[];
trainingDocuments: TrainingDocumentInfo[];
}

// @public
export type TrainStatus = "succeeded" | "partiallySucceeded" | "failed";

// @public
export interface USReceipt extends RecognizedReceipt {
items: USReceiptItem[];
Expand Down Expand Up @@ -592,7 +598,7 @@ export type ValueTypes = "string" | "date" | "time" | "phoneNumber" | "number" |
// Warnings were encountered during analysis:
//
// src/formRecognizerClient.ts:70:3 - (ae-forgotten-export) The symbol "BeginRecognizePollState" needs to be exported by the entry point index.d.ts
// src/formTrainingClient.ts:68:3 - (ae-forgotten-export) The symbol "BeginTrainingPollState" needs to be exported by the entry point index.d.ts
// src/formTrainingClient.ts:66:3 - (ae-forgotten-export) The symbol "BeginTrainingPollState" needs to be exported by the entry point index.d.ts

// (No @packageDocumentation comment for this package)

Expand Down
8 changes: 4 additions & 4 deletions sdk/formrecognizer/ai-form-recognizer/samples/javascript/customModelManagement.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ async function main() {
// First, we see how many custom models we have, and what our limit is
const accountProperties = await client.getAccountProperties();
console.log(
`Our account has ${accountProperties.count} custom models, and we can have at most ${accountProperties.limit} custom models`
`Our account has ${accountProperties.customModelCount} custom models, and we can have at most ${accountProperties.customModelLimit} custom models`
);

// Next, we get a paged async iterator of all of our custom models
const result = client.listModels();
const result = client.listCustomModels();

// We could print out information about first ten models
// and save the first model id for later use
Expand All @@ -49,7 +49,7 @@ async function main() {
}

// Now we'll get the first custom model in the paged list
const model = await client.getModel(firstModel.modelId);
const model = await client.getCustomModel(firstModel.modelId);
console.log(`Model Id: ${model.modelId}`);
console.log(`Status: ${model.status}`);
console.log("Documents used in training: [");
Expand All @@ -61,7 +61,7 @@ async function main() {
// Finally, we can delete this model if we want (for example, if its status is 'invalid')
// await client.deleteModel(firstModel.modelId);
// try {
// const deleted = await client.getModel(firstModel.modelId);
// const deleted = await client.getCustomModel(firstModel.modelId);
// console.log(deleted);
// } catch (err) {
// // Expected
Expand Down
4 changes: 2 additions & 2 deletions sdk/formrecognizer/ai-form-recognizer/samples/javascript/differentiateLabeledUnlabeled.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ async function main() {
// The recognized form fields with a custom model from training without labels will also include data about recognized labels.
const field = form.fields[fieldName];
console.log(
`\tField ${fieldName} has label '${field.fieldLabel.text}' with a confidence score of ${field.confidence}`
`\tField ${fieldName} has label '${field.labelText.text}' with a confidence score of ${field.confidence}`
);
console.log(
`\tField ${fieldName} has value '${field.value}' with a confidence score of ${field.confidence}`
Expand All @@ -63,7 +63,7 @@ async function recognizeCustomForm(path, endpoint, apiKey, labeledModelId) {
console.log("# Recognizing...");
const readStream = fs.createReadStream(path);
const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
const poller = await client.beginRecognizeForms(labeledModelId, readStream, "application/pdf", {
const poller = await client.beginRecognizeCustomForms(labeledModelId, readStream, "application/pdf", {
onProgress: (state) => {
console.log(`\tstatus: ${state.status}`);
}
Expand Down
2 changes: 1 addition & 1 deletion sdk/formrecognizer/ai-form-recognizer/samples/javascript/getBoundingBoxes.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ async function main() {
const readStream = fs.createReadStream(path);

const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
const poller = await client.beginRecognizeForms(modelId, readStream, "application/pdf", {
const poller = await client.beginRecognizeCustomForms(modelId, readStream, "application/pdf", {
onProgress: (state) => {
console.log(`status: ${state.status}`);
}
Expand Down
6 changes: 3 additions & 3 deletions sdk/formrecognizer/ai-form-recognizer/samples/javascript/iteratorModels.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ async function main() {

const client = new FormTrainingClient(endpoint, new AzureKeyCredential(apiKey));

const result = await client.listModels();
const result = await client.listCustomModels();
let i = 0;
for await (const modelInfo of result) {
console.log(`model ${i++}:`);
Expand All @@ -27,7 +27,7 @@ async function main() {

// using `iter.next()`
i = 1;
let iter = client.listModels();
let iter = client.listCustomModels();
let modelItem = await iter.next();
while (!modelItem.done) {
console.log(`model ${i++}: ${modelItem.value.modelId}`);
Expand All @@ -36,7 +36,7 @@ async function main() {

// using `byPage()`
i = 1;
for await (const response of client.listModels().byPage()) {
for await (const response of client.listCustomModels().byPage()) {
for (const modelInfo of response.modelList) {
console.log(`model ${i++}: ${modelInfo.modelId}`);
}
Expand Down
2 changes: 1 addition & 1 deletion sdk/formrecognizer/ai-form-recognizer/samples/javascript/recognizeCustomForm.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ async function main() {
const readStream = fs.createReadStream(path);

const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));
const poller = await client.beginRecognizeForms(modelId, readStream, "application/pdf", {
const poller = await client.beginRecognizeCustomForms(modelId, readStream, "application/pdf", {
onProgress: (state) => {
console.log(`status: ${state.status}`);
}
Expand Down
Loading

0 comments on commit e5cf732

Please sign in to comment.