Web API - External ID

1. Prvý OID v URL ceste:

   Je možné použiť externalid namiesto oid, musí však byť URL kódované (napr. dvojbodka ako %3A).

   http://localhost:81/demodata/countries/ext%3Ax_number_1?select=id

2. OID odkazovaných číselníkov v tele dopytu:

   Pri zadávaní odkazov na číselníky je možné namiesto oid použiť externalid.

   {
   	"storecard_id": "ext:x_number_2"
   }

3. Zmena riadkov v kolekcii:

   Externalid je možné použiť na identifikáciu konkrétneho riadka pri jeho úprave.

   {
   	"rows": {
   		"id": "ext:x_number_3",
   		"text": "test change"
   	}
   }

4. Mazanie riadkov v kolekcii:

   Externalid je možné použiť na určenie riadkov na vymazanie pomocou includeids alebo excludeids.

   {
   	"rows@delete": {
   		"includeids": ["ext:x_number_4"]
   	}
   }

5. Import a export dokumentov:

   Externalid je možné použiť pri odkazovaní na dokumenty v importe alebo exporte.

   {
   	"input_documents": "ext:op_forimport_1",
   	"output_document": "ext:fv_forimportfromop_1"
   }

6. Dávkové spracovanie:

   Pri dávkovom spracovaní operácií update alebo delete je možné používať externalid. URL musí byť správne kódované.

7. Operácia proti serverovému stavu:

   Podpora pre externalid bola doplnená v operáciách ako load, clone a pod.

   Výnimka: Operácia update dohľadáva externalid v cache (nie v databáze), čo znamená, že objekt musí byť v cache načítaný, inak operácia zlyhá.

• Kolekcia ExternalIDs nemá žiadne podkolekcie. Syntax ext: na kolekcii ExternalIDs nie je podporovaná.
• Podpora externalid nebola implementovaná na niekoľkých miestach, ktoré nie sú určené na použitie v Web API alebo na skriptovanie.

# ExternalID je možné používat v různých místech API, kde se běžně používá odkaz na objekt, tzv OID.
# Před vlastním externalid je nutné uvést prefix ext:.
# Systém v takovém případě zkusí dohledat OID pomocí ExternalID. Pokud se nenajde, vyvolá se vyjímka.
# ExternalID jsou v rámci jedné třídy business objektů unikátní - je to hlídáno unikátností
# v databázi.

import base64
import json
import sys
import uuid

import requests
from http_constants.headers import HttpHeaders

session = requests.Session()
headers = {}
headers[HttpHeaders.CONTENT_TYPE] = HttpHeaders.CONTENT_TYPE_VALUES.json
headers[HttpHeaders.AUTHORIZATION] = "Basic " + (
	base64.urlsafe_b64encode(("tester" + ":" + "testerp").encode("utf-8"))
).decode("utf-8")


# Vytvoření nových náhodných ExternalID pro demonstrační použití.
EXTID_FV = "fv_" + str(uuid.uuid4())
EXTID_FV_ROW = "fvrow_" + str(uuid.uuid4())
EXTID_FIRM = "firm_" + str(uuid.uuid4())


# ExternalID je implementované jako kolekce pro skoro každý business objekt a založení nebo změna
# se provádí naprosto stejně jako u jiných kolekcí. A také se zde nepoužívá prefix - tak je se zde uvede
# tak se i uloží, prefix by se v takovém případě bral jako součást ExternalID.

print("\ncreate new issued invoice with externalids:")
body = {
	"firm_id": "3000000101",
	"docqueue_id": "5600000101",
	"storedocqueue_id": "P600000101",
	"description": "text fv 1",
	"externalids": [
		{
			"externalid": f"{EXTID_FV}",
		}
	],
	"rows": [
		{
			"rowtype": 0,
			"text": "original text",
			"division_id": "2100000101",
			"externalids": [{"externalid": f"{EXTID_FV_ROW}"}],
		}
	],
}
response = session.post(
	url="http://localhost:81/demodata/issuedinvoices?select=id,description&expand=externalids,rows(text)",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 201:
	sys.exit(0)
response_body = response.json()
fv_id = response_body["id"]


# ExternalID lze použít v cestě - zatím jen u prvního ID a je třeba ho mít url encoded
# (%3A je dvojtečka ... ale vzhledem k tomu, že může obsahovat v podstatě libovolné znaky,
# je nutné ho urlencodovat celé).
print("\nchange previously created fv by externalid in url:")
body = {"description": "changed via url externalid"}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/ext%3A{EXTID_FV}?select=id,description",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)


# ExternalID lze použít při změně řádky v kolekci. V URL je nyní použité OID, ale
# samozřejmě lze použít ExternalID i v url jako u předchozího příkladu.
print("\nchange row in previously created fv by externalid in collection:")
body = {
	"rows": [
		{
			"id": f"ext:{EXTID_FV_ROW}",
			"text": "change row by externalid",
		}
	],
}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/{fv_id}?expand=rows(id, text)",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)


# ExternalID lze použít pro smazání řádku v kolekci.
print("\ndelete row in previously created fv by externalid in collection:")
body = {
	"rows@delete": {
		"includeids": [f"ext:{EXTID_FV_ROW}"],
	},
}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/{fv_id}?expand=rows",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)


# ExternalID lze použít při změně BO pro identifikaci odkazu do číselníku.

# Nejdřív na nějakou firmu nasetujeme nové ExternalID
print("\nnew externalid for firm:")
body = {
	"externalids": [
		{"externalid": f"{EXTID_FIRM}"},
	],
}
response = session.put(
	url="http://localhost:81/demodata/firms/K000000101?expand=externalids",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)

# A pak změním firmu na FV pomocí tohoto ExternalID
print("\nchange firm on previously created fv by externalid:")
body = {
	"firm_id": f"ext:{EXTID_FIRM}",
}
response = session.put(
	url=f"http://localhost:81/demodata/issuedinvoices/{fv_id}?select=firm_id",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))
if response.status_code != 200:
	sys.exit(0)

Generická podpora: Vo väčšine miest Web API bola podpora externalid implementovaná, ale pokiaľ sa nájdu nové miesta, podpora môže byť doplnená v budúcnosti.

Výhody externalid:

• Jednoznačná identifikácia záznamov bez závislosti na internom ID (oid).
• Flexibilita pri prenášaní identifikátorov medzi systémami.